mirror of
https://github.com/mpv-player/mpv
synced 2024-12-26 00:42:57 +00:00
5368c46453
While DOCS/tech/ contains lots of documentation about mplayer's internals, most of it seems outdated, and hasn't been touched in many years. On the other hand, there still might be useful things in there, but it's hard to tell which parts. Instead of deleting all it, rename the directory to "warn" potential developers that the documentation is completely outdated.
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.
|