DOCS/tech/libvo.txt

   1 libvo --- the library to handle video output    by A'rpi, 2002.04
   2 ============================================
   3
   4 Note: before start on this, read colorspaces.txt !
   5
   6 The constants for different pixelformats are defined in img_format.h,
   7 their usage is mandatory.
   8
   9 WARNING: Please keep in mind that some of this information may be out-dated,
  10 so if you are working on a new vo, consider submitting preliminary patches
  11 very early on. Currently vo_gl is one of the more up-to-date VOs to use
  12 as reference if you are unsure about something and do not want to ask on the
  13 list.
  14 vo_vdpau and vo_direct3d may be a good choice, too, they use different
  15 approaches closer to the sometimes convoluted way DirectX works.
  16
  17 Each vo driver _has_ to implement these:
  18
  19     preinit():
  20         init the video system (to support querying for supported formats)
  21
  22     uninit():
  23       Uninit the whole system, this is on the same "level" as preinit.
  24
  25     control():
  26       Current controls (VOCTRL_QUERY_FORMAT must be implemented,
  27       VOCTRL_DRAW_IMAGE, VOCTRL_FULLSCREEN, VOCTRL_UPDATE_SCREENINFO
  28       should be implemented):
  29          VOCTRL_QUERY_FORMAT  -  queries if a given pixelformat is supported.
  30                 It also returns various flags decsirbing the capabilities
  31                 of the driver with teh given mode. for the flags, see
  32                 file vfcaps.h !
  33                 the most important flags, every driver must properly report
  34                 these:
  35                     0x1  -  supported (with or without conversion)
  36                     0x2  -  supported without conversion (define 0x1 too!)
  37                     0x100  -  driver/hardware handles timing (blocking)
  38                 also SET sw/hw scaling and osd support flags, and flip,
  39                 and accept_stride if you implement VOCTRL_DRAW_IMAGE (see bellow)
  40                 NOTE: VOCTRL_QUERY_FORMAT may be called _before_ first config()
  41                 but is always called between preinit() and uninit()
  42          VOCTRL_GET_IMAGE
  43                 libmpcodecs Direct Rendering interface
  44                 You need to update mpi (mp_image.h) structure, for example,
  45                 look at vo_x11, vo_sdl, vo_xv or mga_common.
  46          VOCTRL_DRAW_IMAGE
  47                 replacement for the current draw_slice/draw_frame way of
  48                 passing video frames. by implementing SET_IMAGE, you'll get
  49                 image in mp_image struct instead of by calling draw_*.
  50                 unless you return VO_TRUE for VOCTRL_DRAW_IMAGE call, the
  51                 old-style draw_* functils will be called!
  52                 Note: draw_slice is still mandatory, for per-slice rendering!
  53          VOCTRL_RESET  -  reset the video device
  54                 This is sent on seeking and similar and is useful if you are
  55                 using a device which prebuffers frames that need to flush them
  56                 before refilling audio/video buffers.
  57          VOCTRL_PAUSE
  58          VOCTRL_RESUME
  59          VOCTRL_GUISUPPORT
  60                 return true only if driver supports co-operation with
  61                 MPlayer's GUI (not yet used by GUI)
  62          VOCTRL_SET_EQUALIZER
  63                 set the video equalizer to the given values
  64                 two arguments are provided: item and value
  65                 item is a string, the possible values are (currently):
  66                     brightness, contrast, saturation, hue
  67          VOCTRL_GET_EQUALIZER
  68                 get the current video equalizer values
  69                 two arguments are provided: item and value
  70                 item is a string, the possible values are (currently):
  71                     brightness, contrast, saturation, hue
  72          VOCTRL_ONTOP
  73                 Makes the player window stay-on-top. Only supported (currently)
  74                 by drivers which use X11, except SDL, as well as directx and
  75                 gl2 under Windows.
  76          VOCTRL_BORDER
  77                 Makes the player window borderless.
  78          VOCTRL_FULLSCREEN
  79                 Switch from and to fullscreen mode
  80          VOCTRL_GET_PANSCAN
  81          VOCTRL_SET_PANSCAN
  82                 Needed to implement pan-scan support ('w' and 'e' keys during
  83                 playback in fullscreen mode)
  84          VOCTRL_START_SLICE
  85                 Called before the first draw_slice of each frame, useful if
  86                 you need to do some set-up work.
  87          VOCTRL_DRAW_EOSD
  88                 Required for EOSD (ASS subtitle) support. Provides all
  89                 information necessary to draw the EOSD for the current video
  90                 frame.
  91          VOCTRL_GET_EOSD_RES
  92                 Required for EOSD (ASS subtitle) support. Informs the ASS
  93                 renderer about the properties of the drawing area (size,
  94                 borders).
  95          VOCTRL_SET_DEINTERLACE
  96          VOCTRL_GET_DEINTERLACE
  97                 Get or set deinterlacing status for VOs that support some kind
  98                 of deinterlacing.
  99          VOCTRL_UPDATE_SCREENINFO
 100                 Should set the xinerama_x, xinerama_y, vo_screenwidth and
 101                 vo_screenheight appropriately for the currently used
 102                 monitor and -xineramascreen option.
 103                 Usually should simply call the w32_update_xinerama_info or
 104                 update_xinerama_info function.
 105                 By supporting this, the VO also requests the newer API
 106                 that sets vo_dx, vo_dy etc. appropriately before config()
 107                 is called.
 108
 109     config():
 110       Set up the video system. You get the dimensions and flags.
 111       width, height: size of the source image
 112       d_width, d_height: wanted scaled/display size (it's a hint)
 113       Flags:
 114         0x01    - force fullscreen (-fs)
 115         0x02    - allow mode switching (-vm)
 116         0x04    - allow software scaling (-zoom)
 117         0x08    - flipping (-flip)
 118       They're defined as VOFLAG_* (see libvo/video_out.h)
 119
 120       IMPORTANT NOTE: config() may be called 0 (zero), 1 or more (2,3...)
 121       times between preinit() and uninit() calls. You MUST handle it, and
 122       you shouldn't crash at second config() call or at uninit() without
 123       any config() call! To make your life easier, vo_config_count is
 124       set to the number of previous config() call, counted from preinit().
 125       It's set by the caller (vf_vo.c), you don't have to increase it!
 126       So, you can check for vo_config_count>0 in uninit() when freeing
 127       resources allocated in config() to avoid crash!
 128
 129       You should implement VOCTRL_UPDATE_SCREENINFO so that vo_dx, vo_dy,
 130       vo_dwidth and vo_dheight are already pre-set to values that take
 131       aspect and -geometry into account. It is also necessary to properly
 132       support multi-monitor setups (if based on x11_common, w32_common).
 133
 134     draw_slice(): this displays YV12 pictures (3 planes, one full sized that
 135          contains brightness (Y), and 2 quarter-sized which the colour-info
 136          (U,V). MPEG codecs (libmpeg2, opendivx) use this. This doesn't have
 137          to display the whole frame, only update small parts of it.
 138          If this is not supported, it must be signaled in QUERY_FORMAT with
 139          VOCAP_NOSLICES.
 140
 141     draw_frame(): this is the older interface, this displays only complete
 142          frames, and can do only packed format (YUY2, RGB/BGR).
 143          Win32 codecs use this (DivX, Indeo, etc).
 144          If you implement VOCTRL_DRAW_IMAGE, you do not need to implement draw_frame.
 145
 146     draw_osd(): this displays subtitles and OSD.
 147          It's a bit tricky to use it, since it's a callback-style stuff.
 148          It should call vo_draw_text() with screen dimension and your
 149          draw_alpha implementation for the pixelformat (function pointer).
 150          The vo_draw_text() checks the characters to draw, and calls
 151          draw_alpha() for each. As a help, osd.c contains draw_alpha for
 152          each pixelformats, use this if possible!
 153          Note that if you do not draw directly onto the video you should
 154          use vo_draw_text_ext() which allows you to specify the border
 155          values etc. needed to draw DVD menu highlights at the correct place.
 156          If you do not want to implement this, you can still use -vf
 157          expand=osd=1 to draw the OSD, or even implement code to insert
 158          this filter automatically.
 159          Make sure you set VFCAP_OSD depending on whether you implemented it
 160          or not.
 161
 162          NOTE: This one will be obsolete soon! But it's still useful when
 163          you want to do tricks, like rendering osd _after_ hardware scaling
 164          (tdfxfb) or render subtitles under of the image (vo_mpegpes, sdl)
 165
 166          NOTE2: above NOTE is probably wrong, there are currently no plans to
 167          obsolete draw_osd, though there is the more advanced EOSD support for
 168          ASS subtitles.
 169
 170     flip_page(): this is called after each frame, this displays the buffer for
 171          real. This is 'swapbuffers' when doublebuffering.
 172          Try to do as little work here as possible, since that affect jitter/
 173          A-V sync.