Documentation

git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@4104 b3059339-0415-0410-9bf9-f77b7e298cf2

1 files changed, 139 insertions, 0 deletions

diff --git a/DOCS/tech/vidix.txt b/DOCS/tech/vidix.txt
new file mode 100644
index 0000000000..3c0d446bc1
--- /dev/null
+++ b/DOCS/tech/vidix.txt
@@ -0,0 +1,139 @@
+		VIDIX - VIDeo Interface for *niX
+		~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+		
+This interface was designed and introduced as interface to userspace drivers
+to provide DGA everywhere where it's possible (unline X11).
+I hope that these drivers will be portable same as X11 (not only on *nix).
+
+What is it:
+- It's portable successor of mga_vid technology which is located in user-space.
+- Unlikely X11 it's provides DGA everywhere where it's possible.
+- Unlikely v4l it provides interface for video playback
+- Unlikely linux's drivers it uses mathematics library.
+
+Why it was developed:
+As said Vladimir Dergachev 
+(http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/gatos/km/km.rfc.txt):
+"0) Motivation
+    v4l, v4l2 and Xv are all suffering from the same problem: attempt to fit 
+    existing multimedia devices into a fixed scheme."
+Well - I tried to implement something similar by motivation.
+
+How it works:
+~~~~~~~~~~~~~
+
+This interface is almost finished. But I guess it can be expanded by developer's
+requests.
+So any suggestions, reports, criticism are gladly accepted.
+
+1) APP calls vixGetVersion to check age of driver ;)
+2) APP calls vixProbe. Driver should return 0 if it can handle something in PC.
+3) APP calls vixGetCapability. Driver should return filled
+    vidix_capability_t.type field at least.
+4) If above calls were succesful then APP calls vixInit function
+   (Driver can have not exported this function in this case call will be
+    skiped).
+5) After initializing of driver APP calls vixGetCapability again
+   (In this case driver must fill every field of struct)
+6) APP calls vixQueryFourcc. Driver should answer - can it configure
+   video memory for given fourcc or not.
+7) APP calls vixConfigPlayback. Driver should prepare BES on this call.
+   APP pass to driver following info:
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   vidix_playback_t.fourcc	- contains fourcc of movie
+   vidix_playback_t.capability	- currently contsinas copy of vidix_capability_t.flags
+   vidix_playback_t.blend_factor- currently unused   
+   vidix_playback_t.src		- currently only x,y,w,h fields are used.
+				  contain original movie size (in pixels)
+				  x and y often are nulls.
+   vidix_playback_t.dest	- x,y,w,h fields contains destinition rectange
+				  on the screen in pixels.
+   vidix_playback_t.num_frames  - maximal # of frames which can be used by APP.
+				  (Currently 10).
+   Driver should fill following fields:
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   vidix_playback_t.num_frames  - real # of frames which will be used by driver.
+				  (Should be less or equal to app's num_frames).
+				  
+   vidix_playback_t.dest.pitch.y   These fields should contain alignment
+   vidix_playback_t.dest.pitch.u - for each Y,U,V plane in bytes.
+   vidix_playback_t.dest.pitch.v   (For packed fourcc only Y value is used)
+   
+   vidix_playback_t.frame_size	- Driver should tell to app which size of
+				      source frame (src.w and src.h) should
+				      use APP (according to pitches and offsets)
+
+   vidix_playback_t.offsets	- offsets from begin of BES memory for each frame
+   
+   vidix_playback_t.offset.y	  These field should contain offset
+   vidix_playback_t.offset.u	- for each Y,U,V plane within frame.
+   vidix_playback_t.offset.v	  (For packed fourcc only Y value is used)
+
+   vidix_playback_t.dga_addr	- Address of BES memory.
+   
+Also see this picture:
+
+VIDEO MEMORY layout:
+ +-----------  It's begin of video memory     End of video memory--------------+
+ |                                                                             |
+ v                                                                             v
+ [      RGB memory                         |         YUV memory    |  UNDEF    ]
+					   ^
+					   |
+					   +---- begin of BES memory
+
+BES MEMORY layout:
+ +-------- begin of BES memory
+ |
+ v
+ [ | |                      |       |       |
+   ^ ^                      ^       ^       ^
+   | |                      |       |       + BEGIN of second frame
+   | |                      |       + BEGIN of V plane
+   | |                      + BEGIN of U plane
+   | +------- BEGIN of Y plane
+   |
+   +--------- BEGIN of first frame
+
+This means that in general case:
+offset of frame != offset of BES
+offset of Y plane != offset of first frame
+
+But often: vidix_playback_t.offsets[0] = vidix_playback_t.offset.y = 0;
+
+Formula: (For Y plane) copy source to:
+		  vidix_playback_t.dga_addr +
+		  vidix_playback_t.offsets[i] +
+		  vidix_playback_t.offset.y
+
+8) APP calls vixPlaybackOn. Driver should activate BES on this call.
+9) PLAYBACK. Driver should sleep here ;)
+   But during playback can be called:
+     vixFrameSelect (if this function is exported)
+	Driver should prepare and activate corresponded frame.
+	This function is used only for double and trilpe buffering and
+	never used for single buffering playback.
+     vixGet(Set)GrKeys (if this function is exported)
+	This interface should be tuned but intriduced for overlapped playback
+	and video effects (TYPE_FX)
+     vixPlaybackGet(Set)Eq (if this function is exported)
+	For color correction.
+10) APP calls vixPlaybackOff. Driver should deactivate BES on this call.
+11) If vixDestroy is defined APP calls this function before unloading driver
+    from memory.
+    
+    
+What functions are mandatory:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vixGetVersion
+vixProbe
+vixGetCapability
+vixQueryFourcc
+vixConfigPlayback
+vixPlaybackOn
+vixPlaybackOff
+
+All other functions are optionaly.
+
+Please send your suggestions, reports, feedback to mplayer-dev-eng@mplayerhq.hu
+Best regards! Nick Kurshev.