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 Each vo driver _has_ to implement these:
  10
  11     preinit():
  12         init the video system (to support querying for supported formats)
  13
  14     uninit():
  15       Uninit the whole system, this is on the same "level" as preinit.
  16
  17     control():
  18       Current controls:
  19          VOCTRL_QUERY_FORMAT  -  queries if a given pixelformat is supported.
  20                 It also returns various flags decsirbing the capabilities
  21                 of the driver with teh given mode. for the flags, see
  22                 file vfcaps.h !
  23                 the most important flags, every driver must properly report
  24                 these:
  25                     0x1  -  supported (with or without conversion)
  26                     0x2  -  supported without conversion (define 0x1 too!)
  27                     0x100  -  driver/hardware handles timing (blocking)
  28                 also SET sw/hw scaling and osd support flags, and flip,
  29                 and accept_stride if you implement VOCTRL_DRAW_IMAGE (see bellow)
  30                 NOTE: VOCTRL_QUERY_FORMAT may be called _before_ first config()
  31                 but is always called between preinit() and uninit()
  32          VOCTRL_GET_IMAGE
  33                 libmpcodecs Direct Rendering interface
  34                 You need to update mpi (mp_image.h) structure, for example,
  35                 look at vo_x11, vo_sdl, vo_xv or mga_common.
  36          VOCTRL_DRAW_IMAGE
  37                 replacement for the current draw_slice/draw_frame way of
  38                 passing video frames. by implementing SET_IMAGE, you'll get
  39                 image in mp_image struct instead of by calling draw_*.
  40                 unless you return VO_TRUE for VOCTRL_DRAW_IMAGE call, the
  41                 old-style draw_* functils will be called!
  42                 Note: draw_slice is still mandatory, for per-slice rendering!
  43          VOCTRL_RESET  -  reset the video device
  44                 This is sent on seeking and similar and is useful if you are
  45                 using a device which prebuffers frames that need to flush them
  46                 before refilling audio/video buffers.
  47          VOCTRL_PAUSE
  48          VOCTRL_RESUME
  49          VOCTRL_GUISUPPORT
  50                 return true only if driver supports co-operation with
  51                 MPlayer's GUI (not yet used by GUI)
  52          VOCTRL_SET_EQUALIZER
  53                 set the video equalizer to the given values
  54                 two arguments are provided: item and value
  55                 item is a string, the possible values are (currently):
  56                     brightness, contrast, saturation, hue
  57          VOCTRL_GET_EQUALIZER
  58                 get the current video equalizer values
  59                 two arguments are provided: item and value
  60                 item is a string, the possible values are (currently):
  61                     brightness, contrast, saturation, hue
  62          VOCTRL_ONTOP
  63                 Makes the player window stay-on-top. Only supported (currently)
  64                 by drivers which use X11, except SDL, as well as directx and
  65                 gl2 under Windows.
  66          VOCTRL_BORDER
  67                 Makes the player window borderless.  Only supported by directx.
  68
  69     config():
  70       Set up the video system. You get the dimensions and flags.
  71       width, height: size of the source image
  72       d_width, d_height: wanted scaled/display size (it's a hint)
  73       Flags:
  74         0x01    - force fullscreen (-fs)
  75         0x02    - allow mode switching (-vm)
  76         0x04    - allow software scaling (-zoom)
  77         0x08    - flipping (-flip)
  78       They're defined as VOFLAG_* (see libvo/video_out.h)
  79
  80       IMPORTANT NOTE: config() may be called 0 (zero), 1 or more (2,3...)
  81       times between preinit() and uninit() calls. You MUST handle it, and
  82       you shouldn't crash at second config() call or at uninit() without
  83       any config() call! To make your life easier, vo_config_count is
  84       set to the number of previous config() call, counted from preinit().
  85       It's set by the caller (vf_vo.c), you don't have to increase it!
  86       So, you can check for vo_config_count>0 in uninit() when freeing
  87       resources allocated in config() to avoid crash!
  88
  89       You should call geometry() in config() to enable user defined
  90       window size and position. The code should look as following:
  91       ---
  92       set x,y,w,h to the values supplied by the caller or to those you deam
  93       useful.
  94       call geometry(&x, &y, &w, &h, screenw, screenh)
  95       call aspect()
  96       ---
  97       see libvo/geometry.c for further information
  98
  99     draw_slice(): this displays YV12 pictures (3 planes, one full sized that
 100          contains brightness (Y), and 2 quarter-sized which the colour-info
 101          (U,V). MPEG codecs (libmpeg2, opendivx) use this. This doesn't have
 102          to display the whole frame, only update small parts of it.
 103
 104     draw_frame(): this is the older interface, this displays only complete
 105          frames, and can do only packed format (YUY2, RGB/BGR).
 106          Win32 codecs use this (DivX, Indeo, etc).
 107          If you implement VOCTRL_DRAW_IMAGE, you can left draw_frame.
 108
 109     draw_osd(): this displays subtitles and OSD.
 110          It's a bit tricky to use it, since it's a callback-style stuff.
 111          It should call vo_draw_text() with screen dimension and your
 112          draw_alpha implementation for the pixelformat (function pointer).
 113          The vo_draw_text() checks the characters to draw, and calls
 114          draw_alpha() for each. As a help, osd.c contains draw_alpha for
 115          each pixelformats, use this if possible!
 116
 117          NOTE: This one will be obsolete soon! But it's still useful when
 118          you want to do tricks, like rendering osd _after_ hardware scaling
 119          (tdfxfb) or render subtitles under of the image (vo_mpegpes, sdl)
 120
 121     flip_page(): this is called after each frame, this diplays the buffer for
 122          real. This is 'swapbuffers' when doublebuffering.
 123