mirror of https://github.com/mpv-player/mpv
174 lines
8.8 KiB
Plaintext
174 lines
8.8 KiB
Plaintext
libvo --- the library to handle video output by A'rpi, 2002.04
|
|
============================================
|
|
|
|
Note: before start on this, read colorspaces.txt !
|
|
|
|
The constants for different pixelformats are defined in img_format.h,
|
|
their usage is mandatory.
|
|
|
|
WARNING: Please keep in mind that some of this information may be out-dated,
|
|
so if you are working on a new vo, consider submitting preliminary patches
|
|
very early on. Currently vo_gl is one of the more up-to-date VOs to use
|
|
as reference if you are unsure about something and do not want to ask on the
|
|
list.
|
|
vo_vdpau and vo_direct3d may be a good choice, too, they use different
|
|
approaches closer to the sometimes convoluted way DirectX works.
|
|
|
|
Each vo driver _has_ to implement these:
|
|
|
|
preinit():
|
|
init the video system (to support querying for supported formats)
|
|
|
|
uninit():
|
|
Uninit the whole system, this is on the same "level" as preinit.
|
|
|
|
control():
|
|
Current controls (VOCTRL_QUERY_FORMAT must be implemented,
|
|
VOCTRL_DRAW_IMAGE, VOCTRL_FULLSCREEN, VOCTRL_UPDATE_SCREENINFO
|
|
should be implemented):
|
|
VOCTRL_QUERY_FORMAT - queries if a given pixelformat is supported.
|
|
It also returns various flags decsirbing the capabilities
|
|
of the driver with teh given mode. for the flags, see
|
|
file vfcaps.h !
|
|
the most important flags, every driver must properly report
|
|
these:
|
|
0x1 - supported (with or without conversion)
|
|
0x2 - supported without conversion (define 0x1 too!)
|
|
0x100 - driver/hardware handles timing (blocking)
|
|
also SET sw/hw scaling and osd support flags, and flip,
|
|
and accept_stride if you implement VOCTRL_DRAW_IMAGE (see bellow)
|
|
NOTE: VOCTRL_QUERY_FORMAT may be called _before_ first config()
|
|
but is always called between preinit() and uninit()
|
|
VOCTRL_GET_IMAGE
|
|
libmpcodecs Direct Rendering interface
|
|
You need to update mpi (mp_image.h) structure, for example,
|
|
look at vo_x11, vo_sdl, vo_xv or mga_common.
|
|
VOCTRL_DRAW_IMAGE
|
|
replacement for the current draw_slice/draw_frame way of
|
|
passing video frames. by implementing SET_IMAGE, you'll get
|
|
image in mp_image struct instead of by calling draw_*.
|
|
unless you return VO_TRUE for VOCTRL_DRAW_IMAGE call, the
|
|
old-style draw_* functils will be called!
|
|
Note: draw_slice is still mandatory, for per-slice rendering!
|
|
VOCTRL_RESET - reset the video device
|
|
This is sent on seeking and similar and is useful if you are
|
|
using a device which prebuffers frames that need to flush them
|
|
before refilling audio/video buffers.
|
|
VOCTRL_PAUSE
|
|
VOCTRL_RESUME
|
|
VOCTRL_GUISUPPORT
|
|
return true only if driver supports co-operation with
|
|
MPlayer's GUI (not yet used by GUI)
|
|
VOCTRL_SET_EQUALIZER
|
|
set the video equalizer to the given values
|
|
two arguments are provided: item and value
|
|
item is a string, the possible values are (currently):
|
|
brightness, contrast, saturation, hue
|
|
VOCTRL_GET_EQUALIZER
|
|
get the current video equalizer values
|
|
two arguments are provided: item and value
|
|
item is a string, the possible values are (currently):
|
|
brightness, contrast, saturation, hue
|
|
VOCTRL_ONTOP
|
|
Makes the player window stay-on-top. Only supported (currently)
|
|
by drivers which use X11, except SDL, as well as directx and
|
|
gl2 under Windows.
|
|
VOCTRL_BORDER
|
|
Makes the player window borderless.
|
|
VOCTRL_FULLSCREEN
|
|
Switch from and to fullscreen mode
|
|
VOCTRL_GET_PANSCAN
|
|
VOCTRL_SET_PANSCAN
|
|
Needed to implement pan-scan support ('w' and 'e' keys during
|
|
playback in fullscreen mode)
|
|
VOCTRL_START_SLICE
|
|
Called before the first draw_slice of each frame, useful if
|
|
you need to do some set-up work.
|
|
VOCTRL_DRAW_EOSD
|
|
Required for EOSD (ASS subtitle) support. Provides all
|
|
information necessary to draw the EOSD for the current video
|
|
frame.
|
|
VOCTRL_GET_EOSD_RES
|
|
Required for EOSD (ASS subtitle) support. Informs the ASS
|
|
renderer about the properties of the drawing area (size,
|
|
borders).
|
|
VOCTRL_SET_DEINTERLACE
|
|
VOCTRL_GET_DEINTERLACE
|
|
Get or set deinterlacing status for VOs that support some kind
|
|
of deinterlacing.
|
|
VOCTRL_UPDATE_SCREENINFO
|
|
Should set the xinerama_x, xinerama_y, vo_screenwidth and
|
|
vo_screenheight appropriately for the currently used
|
|
monitor and -xineramascreen option.
|
|
Usually should simply call the w32_update_xinerama_info or
|
|
update_xinerama_info function.
|
|
By supporting this, the VO also requests the newer API
|
|
that sets vo_dx, vo_dy etc. appropriately before config()
|
|
is called.
|
|
|
|
config():
|
|
Set up the video system. You get the dimensions and flags.
|
|
width, height: size of the source image
|
|
d_width, d_height: wanted scaled/display size (it's a hint)
|
|
Flags:
|
|
0x01 - force fullscreen (-fs)
|
|
0x02 - allow mode switching (-vm)
|
|
0x04 - allow software scaling (-zoom)
|
|
0x08 - flipping (-flip)
|
|
They're defined as VOFLAG_* (see libvo/video_out.h)
|
|
|
|
IMPORTANT NOTE: config() may be called 0 (zero), 1 or more (2,3...)
|
|
times between preinit() and uninit() calls. You MUST handle it, and
|
|
you shouldn't crash at second config() call or at uninit() without
|
|
any config() call! To make your life easier, vo_config_count is
|
|
set to the number of previous config() call, counted from preinit().
|
|
It's set by the caller (vf_vo.c), you don't have to increase it!
|
|
So, you can check for vo_config_count>0 in uninit() when freeing
|
|
resources allocated in config() to avoid crash!
|
|
|
|
You should implement VOCTRL_UPDATE_SCREENINFO so that vo_dx, vo_dy,
|
|
vo_dwidth and vo_dheight are already pre-set to values that take
|
|
aspect and -geometry into account. It is also necessary to properly
|
|
support multi-monitor setups (if based on x11_common, w32_common).
|
|
|
|
draw_slice(): this displays YV12 pictures (3 planes, one full sized that
|
|
contains brightness (Y), and 2 quarter-sized which the colour-info
|
|
(U,V). MPEG codecs (libmpeg2, opendivx) use this. This doesn't have
|
|
to display the whole frame, only update small parts of it.
|
|
If this is not supported, it must be signaled in QUERY_FORMAT with
|
|
VOCAP_NOSLICES.
|
|
|
|
draw_frame(): this is the older interface, this displays only complete
|
|
frames, and can do only packed format (YUY2, RGB/BGR).
|
|
Win32 codecs use this (DivX, Indeo, etc).
|
|
If you implement VOCTRL_DRAW_IMAGE, you do not need to implement draw_frame.
|
|
|
|
draw_osd(): this displays subtitles and OSD.
|
|
It's a bit tricky to use it, since it's a callback-style stuff.
|
|
It should call vo_draw_text() with screen dimension and your
|
|
draw_alpha implementation for the pixelformat (function pointer).
|
|
The vo_draw_text() checks the characters to draw, and calls
|
|
draw_alpha() for each. As a help, osd.c contains draw_alpha for
|
|
each pixelformats, use this if possible!
|
|
Note that if you do not draw directly onto the video you should
|
|
use vo_draw_text_ext() which allows you to specify the border
|
|
values etc. needed to draw DVD menu highlights at the correct place.
|
|
If you do not want to implement this, you can still use -vf
|
|
expand=osd=1 to draw the OSD, or even implement code to insert
|
|
this filter automatically.
|
|
Make sure you set VFCAP_OSD depending on whether you implemented it
|
|
or not.
|
|
|
|
NOTE: This one will be obsolete soon! But it's still useful when
|
|
you want to do tricks, like rendering osd _after_ hardware scaling
|
|
(tdfxfb) or render subtitles under of the image (vo_mpegpes, sdl)
|
|
|
|
NOTE2: above NOTE is probably wrong, there are currently no plans to
|
|
obsolete draw_osd, though there is the more advanced EOSD support for
|
|
ASS subtitles.
|
|
|
|
flip_page(): this is called after each frame, this displays the buffer for
|
|
real. This is 'swapbuffers' when doublebuffering.
|
|
Try to do as little work here as possible, since that affect jitter/
|
|
A-V sync.
|