annotate DOCS/tech/libvo.txt @ 31311:9ce59b78dbfd

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