annotate DOCS/tech/vidix.txt @ 25563:1e9ef4ed8e8f

Relicense file to GPL v2 or later with the permission of Rudolf Marek, the author and update his email contact address.

		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		- x,y,w,h fields contain original movie size
				  (in pixels) x and y often are nulls.
   vidix_playback_t.src.pitch.y   These fields contain source pitches
   vidix_playback_t.src.pitch.u - for each Y,U,V plane in bytes.
   vidix_playback_t.src.pitch.v   (For packed fourcc only Y value is used)
				  They are hints for driver to use same destinition
				  pitches as in source memory (to speed up
				  memcpy process).
				  Note: when source pitches are unknown or
				  variable these field will be filled into 0.
   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.

Useful links:
~~~~~~~~~~~~~
Guide to DTV		http://www.digitaltelevision.com/dtvbook/toc.shtml
Fourcc			http://www.webartz.com/fourcc/
MPEG			http://www.mpeg.org/MPEG/index.html
Analog colors		http://www.miranda.com/en/app_notes/TN/TN-05/TN-05.htm

Please send your suggestions, reports, feedback to [e-mail]
Best regards! Nick Kurshev.