DOCS/tech/vidix.txt

   1                 VIDIX - VIDeo Interface for *niX
   2                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3
   4 This interface was designed and introduced as interface to userspace drivers
   5 to provide DGA everywhere where it's possible (unline X11).
   6 I hope that these drivers will be portable same as X11 (not only on *nix).
   7
   8 What is it:
   9 - It's portable successor of mga_vid technology which is located in user-space.
  10 - Unlikely X11 it's provides DGA everywhere where it's possible.
  11 - Unlikely v4l it provides interface for video playback
  12 - Unlikely linux's drivers it uses mathematics library.
  13
  14 Why it was developed:
  15 As said Vladimir Dergachev
  16 (http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/gatos/km/km.rfc.txt):
  17 "0) Motivation
  18     v4l, v4l2 and Xv are all suffering from the same problem: attempt to fit
  19     existing multimedia devices into a fixed scheme."
  20 Well - I tried to implement something similar by motivation.
  21
  22 How it works:
  23 ~~~~~~~~~~~~~
  24
  25 This interface is almost finished. But I guess it can be expanded by developer's
  26 requests.
  27 So any suggestions, reports, criticism are gladly accepted.
  28
  29 1) APP calls vixGetVersion to check age of driver ;)
  30 2) APP calls vixProbe. Driver should return 0 if it can handle something in PC.
  31 3) APP calls vixGetCapability. Driver should return filled
  32     vidix_capability_t.type field at least.
  33 4) If above calls were succesful then APP calls vixInit function
  34    (Driver can have not exported this function in this case call will be
  35     skiped).
  36 5) After initializing of driver APP calls vixGetCapability again
  37    (In this case driver must fill every field of struct)
  38 6) APP calls vixQueryFourcc. Driver should answer - can it configure
  39    video memory for given fourcc or not.
  40 7) APP calls vixConfigPlayback. Driver should prepare BES on this call.
  41    APP pass to driver following info:
  42    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  43    vidix_playback_t.fourcc      - contains fourcc of movie
  44    vidix_playback_t.capability  - currently contsinas copy of vidix_capability_t.flags
  45    vidix_playback_t.blend_factor- currently unused
  46    vidix_playback_t.src         - x,y,w,h fields contain original movie size
  47                                   (in pixels) x and y often are nulls.
  48    vidix_playback_t.src.pitch.y   These fields contain source pitches
  49    vidix_playback_t.src.pitch.u - for each Y,U,V plane in bytes.
  50    vidix_playback_t.src.pitch.v   (For packed fourcc only Y value is used)
  51                                   They are hints for driver to use same destinition
  52                                   pitches as in source memory (to speed up
  53                                   memcpy process).
  54                                   Note: when source pitches are unknown or
  55                                   variable these field will be filled into 0.
  56    vidix_playback_t.dest        - x,y,w,h fields contains destinition rectange
  57                                   on the screen in pixels.
  58    vidix_playback_t.num_frames  - maximal # of frames which can be used by APP.
  59                                   (Currently 10).
  60    Driver should fill following fields:
  61    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  62    vidix_playback_t.num_frames  - real # of frames which will be used by driver.
  63                                   (Should be less or equal to app's num_frames).
  64
  65    vidix_playback_t.dest.pitch.y   These fields should contain alignment
  66    vidix_playback_t.dest.pitch.u - for each Y,U,V plane in bytes.
  67    vidix_playback_t.dest.pitch.v   (For packed fourcc only Y value is used)
  68
  69    vidix_playback_t.frame_size  - Driver should tell to app which size of
  70                                       source frame (src.w and src.h) should
  71                                       use APP (according to pitches and offsets)
  72
  73    vidix_playback_t.offsets     - offsets from begin of BES memory for each frame
  74
  75    vidix_playback_t.offset.y      These field should contain offset
  76    vidix_playback_t.offset.u    - for each Y,U,V plane within frame.
  77    vidix_playback_t.offset.v      (For packed fourcc only Y value is used)
  78
  79    vidix_playback_t.dga_addr    - Address of BES memory.
  80
  81 Also see this picture:
  82
  83 VIDEO MEMORY layout:
  84  +-----------  It's begin of video memory     End of video memory--------------+
  85  |                                                                             |
  86  v                                                                             v
  87  [      RGB memory                         |         YUV memory    |  UNDEF    ]
  88                                            ^
  89                                            |
  90                                            +---- begin of BES memory
  91
  92 BES MEMORY layout:
  93  +-------- begin of BES memory
  94  |
  95  v
  96  [ | |                      |       |       |
  97    ^ ^                      ^       ^       ^
  98    | |                      |       |       + BEGIN of second frame
  99    | |                      |       + BEGIN of V plane
 100    | |                      + BEGIN of U plane
 101    | +------- BEGIN of Y plane
 102    |
 103    +--------- BEGIN of first frame
 104
 105 This means that in general case:
 106 offset of frame != offset of BES
 107 offset of Y plane != offset of first frame
 108
 109 But often: vidix_playback_t.offsets[0] = vidix_playback_t.offset.y = 0;
 110
 111 Formula: (For Y plane) copy source to:
 112                   vidix_playback_t.dga_addr +
 113                   vidix_playback_t.offsets[i] +
 114                   vidix_playback_t.offset.y
 115
 116 8) APP calls vixPlaybackOn. Driver should activate BES on this call.
 117 9) PLAYBACK. Driver should sleep here ;)
 118    But during playback can be called:
 119      vixFrameSelect (if this function is exported)
 120         Driver should prepare and activate corresponded frame.
 121         This function is used only for double and trilpe buffering and
 122         never used for single buffering playback.
 123      vixGet(Set)GrKeys (if this function is exported)
 124         This interface should be tuned but intriduced for overlapped playback
 125         and video effects (TYPE_FX)
 126      vixPlaybackGet(Set)Eq (if this function is exported)
 127         For color correction.
 128 10) APP calls vixPlaybackOff. Driver should deactivate BES on this call.
 129 11) If vixDestroy is defined APP calls this function before unloading driver
 130     from memory.
 131
 132
 133 What functions are mandatory:
 134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 135 vixGetVersion
 136 vixProbe
 137 vixGetCapability
 138 vixQueryFourcc
 139 vixConfigPlayback
 140 vixPlaybackOn
 141 vixPlaybackOff
 142
 143 All other functions are optionaly.
 144
 145 Useful links:
 146 ~~~~~~~~~~~~~
 147 Guide to DTV            http://www.digitaltelevision.com/dtvbook/toc.shtml
 148 Fourcc                  http://www.webartz.com/fourcc/
 149 MPEG                    http://www.mpeg.org/MPEG/index.html
 150 Analog colors           http://www.miranda.com/en/app_notes/TN/TN-05/TN-05.htm
 151
 152 Please send your suggestions, reports, feedback to mplayer-dev-eng@mplayerhq.hu
 153 Best regards! Nick Kurshev.