Debian Codegraph @

doc/dvdauthor.sgml

raw
1 <refentry id="dvdauthor">
2
3 <refmeta>
4 <refentrytitle>dvdauthor</refentrytitle>
5 <manvolnum>1</manvolnum>
6 </refmeta>
7
8 <refnamediv>
9 <refname>dvdauthor</refname>
10 <refpurpose>assembles multiple mpeg program streams into a suitable DVD filesystem</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv>
14 <cmdsynopsis>
15 <command>dvdauthor</command>
16 <arg>-o <replaceable>output-dir</replaceable></arg>
17 <arg choice="req">-x <replaceable>xml-control-file</replaceable></arg>
18 </cmdsynopsis>
19 <cmdsynopsis>
20 <command>dvdauthor</command>
21 <arg>-o <replaceable>output-dir</replaceable></arg>
22 <group><arg>-j</arg><arg>--jumppad</arg><arg>-g</arg><arg>--allgprm</arg></group>
23 <group><arg>-T</arg><arg>--toc</arg></group>
24 <arg><replaceable>menu or title options</replaceable></arg>
25 </cmdsynopsis>
26 </refsynopsisdiv>
27
28 <refsect1><title>DVD Background</title>
29 <para>
30
31 At a high level, a DVD is a collection of menus and titles.
32 Conceptually, a menu contains buttons which can be assigned actions
33 and provides a list of choices to the end user, while a title contains
34 the main content of the DVD. However, in reality many of the features
35 available in menus (including buttons, pausing, and looping) are also
36 available in titles.
37
38 </para>
39 <para>
40
41 The menus and titles are divided into titlesets and the VMGM menu set.
42 A titleset can contain a number of menus and titles which are meant to
43 act together. The "menu", "audio", "subtitle", and "angle" buttons on
44 the DVD player's remote control will all access menus in the same
45 titleset as the title which is being played. All the titles and menus
46 of a given titleset have the same video, audio, and subtitle settings
47 (the definitions for the menus are independent from the definitions
48 for the titles), so if you want to have different settings (for
49 example widescreen vs standard aspect ratios), then you need separate
50 titlesets. Titlesets are not meant to jump to one another, so the
51 VMGM menu domain is used. It is a collection of menus (no titles)
52 that can access the menus and titles of all the titlesets.
53
54 </para>
55 <para>
56
57 One of the most frustrating things when deciding how to author a DVD
58 is that there are often many ways to accomplish the same task. For
59 example, you must decide whether to locate menus at the VMGM level or
60 the titleset level. A typical setup is to locate the high level menus
61 at the VMGM level, and the low level configuration menus (scene /
62 audio / subtitle selection) at the titleset. If there are DVD extras,
63 perhaps with a lower quality audio track and a 4:3 aspect ratio, then
64 they would be in a separate titleset with a menu to select among the
65 extras located at the titleset level.
66
67 </para>
68 </refsect1>
69 <refsect1><title>dvdauthor Description</title>
70
71 <para><command>dvdauthor</command> works in discrete operations. It
72 authors each titleset one at a time, and then finally authors the VMGM
73 to complete the disc. At that point the contents can be written out
74 to a DVD. If you are controlling <command>dvdauthor</command> with
75 command line arguments, then each step will occur independently;
76 however if you are using the XML control file, then you have the
77 option of combining some or all the steps into one.</para>
78
79 <para>The VOBs passed to <command>dvdauthor</command> must have DVD
80 NAV (VOBU) packets multiplexed in at the correct locations. Many
81 tools can do this, including <command>mplex</command> from mjpegtools
82 1.6.0 or later. <command>dvdauthor</command> will then fill these
83 packets in with the correct data. Special care has been taken to
84 ensure <command>dvdauthor</command> is fifo compliant; that is every
85 source VOB can be the output of another program (such as
86 <command>mplex</command>). This can make execution faster on many
87 systems by avoiding extra filesystem accesses.</para>
88
89 </refsect1>
90
91 <refsect1><title>Command Line Description</title>
92
93 <variablelist>
94
95 <varlistentry><term><literal>-o <replaceable>output-dir</replaceable></literal></term>
96 <term><literal>-O <replaceable>output-dir</replaceable></literal></term>
97 <listitem><para>The destination directory to store the DVD-Video file structure in.
98 If -O is specified, then any existing directory is (safely) deleted (only items that
99 look like part of a DVD-Video structure are removed).</para></listitem></varlistentry>
100
101 <varlistentry><term><literal>-x <replaceable>xml-control-file</replaceable></literal></term>
102 <listitem><para>Specifies the control file describing the output structure to create.</para></listitem></varlistentry>
103
104 </variablelist>
105
106 <para>Note that the remaining command-line options are <emphasis>deprecated</emphasis>. Use the
107 XML control file instead.</para>
108
109 <variablelist>
110
111 <varlistentry><term><literal>-j</literal></term><term><literal>--jumppad</literal></term>
112 <listitem><para>Enables the creation of jumppads, which allow greater flexibility in choosing jump/call destinations.</para></listitem></varlistentry>
113
114 <varlistentry><term><literal>-g</literal></term><term><literal>--allgprm</literal></term>
115 <listitem><para>Enable the use of all 16 general purpose registers. Prohibits the use of jumppad and some complex expressions that require temporary registers.</para></listitem></varlistentry>
116
117 <varlistentry><term><literal>-T</literal></term>
118 <listitem><para>Creates the table of contents file instead of a
119 titleset. If this option is used, it should be listed first, and you
120 may not specify any titles.</para></listitem>
121 </varlistentry>
122
123
124 <varlistentry><term><literal>-m</literal></term>
125 <listitem><para>Creates a menu.</para></listitem></varlistentry>
126
127 <varlistentry><term><literal>-t</literal></term>
128 <listitem><para>Creates a title.</para></listitem></varlistentry>
129
130 <varlistentry><term><literal>-v <replaceable>video-opts</replaceable></literal></term><term><literal>--video=<replaceable>video-opts</replaceable></literal></term>
131 <listitem><para>A plus (+) separated list of video options. Dvdauthor
132 will try to infer any unspecified options. pal, ntsc, 4:3, 16:9,
133 720xfull, 720x576, 720x480, 704xfull, 704x576, 704x480, 352xfull,
134 352x576, 352x480, 352xhalf, 352x288, 352x240, nopanscan, noletterbox, crop.
135 Default is 4:3, 720xfull</para></listitem></varlistentry>
136
137 <varlistentry><term><literal>-a <replaceable>audio-opts</replaceable></literal></term><term><literal>--audio=<replaceable>audio-opts</replaceable></literal></term>
138 <listitem><para>A plus (+) separated list of options for an audio
139 track, with each track separated by a comma (,). For example -a
140 ac3+en,mp2+de specifies two audio tracks: the first is an English
141 track encoded in AC3, the second is a German track encoded using
142 MPEG-1 layer 2 compression. ac3, mp2, pcm, dts, 16bps, 20bps, 24bps,
143 drc, surround, nolang, 1ch, 2ch, 3ch, 4ch, 5ch, 6ch, 7ch, 8ch, and any
144 two letter ISO 639 language abbreviation. Default is 1 track, mp2,
145 20bps, nolang, 2ch. 'ac3' implies drc, 6ch.
146 </para></listitem></varlistentry>
147
148 <varlistentry><term><literal>-s <replaceable>subpicture-opts</replaceable></literal></term><term><literal>--subpictures=<replaceable>subpicture-opts</replaceable></literal></term>
149 <listitem><para>A plus (+) separated list of options for a subpicture
150 track, with each track separated by a comma (,). nolang and any two
151 letter language abbreviation (see -a) Default is no subpicture
152 tracks.</para></listitem>
153 </varlistentry>
154
155 <varlistentry><term><literal>-e <replaceable>entry(s)</replaceable></literal></term><term><literal>--entry=<replaceable>entry(s)</replaceable></literal></term>
156 <listitem><para>Makes the current menu the default for certain
157 circumstances. It is a comma separated list of any of:</para><para>for
158 TOC menus: title</para><para>for VTS menus: root, ptt, audio,
159 subtitle, angle</para></listitem>
160 </varlistentry>
161
162 <varlistentry><term><literal>-p <replaceable>palette-file</replaceable></literal></term><term><literal>--palette=<replaceable>palette-file</replaceable></literal></term>
163 <listitem><para>Specifies where to get the subpicture
164 palette. Settable per title and per menu. If the filename ends in .rgb
165 (case insensitive) then it is assumed to be RGB, otherwise it is
166 YUV. Entries should be 6 hexadecimal
167 digits. <replaceable>FILE</replaceable> defaults to
168 xste-palette.dat</para></listitem>
169 </varlistentry>
170
171 <varlistentry><term><literal>-c <replaceable>chapterpts</replaceable></literal></term><term><literal>--chapters=<replaceable>chapterpts</replaceable></literal></term>
172 <listitem><para>Specifies a comma (,) separated list of chapter
173 markers. Each marker is of the form [[h:]mm:]ss[.frac] and is relative
174 to the SCR of the next file listed (independent of any timestamp
175 transposing that occurs within dvdauthor). The chapter markers ONLY
176 apply to the next file listed. Defaults to 0.</para></listitem>
177 </varlistentry>
178
179 <varlistentry><term><literal>-f <replaceable>mpeg-file</replaceable></literal></term><term><literal>--file=<replaceable>mpeg-file</replaceable></literal></term><term><literal><replaceable>mpeg-file</replaceable></literal></term>
180 <listitem><para>Specifies either a file, a pipe, or a shell command
181 ending in | which supplies an MPEG-2 system stream with VOB sectors
182 inserted in the appropriate places (using mplex -f 8 to
183 generate)</para></listitem>
184 </varlistentry>
185
186 <varlistentry><term><literal>-b <replaceable>buttondef</replaceable></literal></term><term><literal>--button=<replaceable>X1xY1-X2xY2,commandlist</replaceable></literal></term>
187 <listitem><para>creates a button of the specified size. See
188 LANGUAGE DESCRIPTION for a description of <replaceable>commandlist</replaceable>.</para></listitem>
189 </varlistentry>
190
191 <varlistentry><term><literal>-i <replaceable>[pre|post]=commandlist</replaceable></literal></term><term><literal>--instructions=<replaceable>[pre|post]=commandlist</replaceable></literal></term>
192 <listitem><para>Executes the <replaceable>commandlist</replaceable>
193 instructions either before or at the end of the menu/title. See
194 LANGUAGE DESCRIPTION for the format of <replaceable>commandlist.</replaceable></para></listitem>
195 </varlistentry>
196
197
198 </variablelist>
199
200 </refsect1>
201
202 <refsect1><title>XML Description</title>
203 <para>
204 Here is the basic structure of the control file:
205 </para>
206 <synopsis>
207 &lt;dvdauthor [dest="<replaceable>output-dir</replaceable>"] [jumppad="1|on|yes" | allgprm="1|on|yes"] [format="ntsc|pal"] [provider="<replaceable>provider</replaceable>"]&gt;
208 &lt;vmgm&gt;
209 [&lt;fpc&gt;<replaceable>commands;</replaceable>&lt;/fpc&gt;]
210 &lt;menus [lang="<replaceable>language-code</replaceable>"]&gt;
211 &lt;video [format="ntsc|pal"] [aspect="4:3|16:9"]
212 [resolution="<replaceable>XxY</replaceable>"] [caption="field1|field2"]
213 [widescreen="nopanscan|noletterbox|crop"] /&gt;
214 &lt;audio [format="mp2|ac3|dts|pcm"] [channels="<replaceable>numchannels</replaceable>"]
215 [quant="16bps|20bps|24bps|drc"] [dolby="surround"]
216 [samplerate="48khz|96khz"] [lang="<replaceable>language</replaceable>"]
217 [content="normal|impaired|comments1|comments2"] /&gt;
218 [&lt;audio ... /&gt;]
219 &lt;subpicture [lang="<replaceable>language-code</replaceable>"]&gt;
220 &lt;stream mode="normal|widescreen|letterbox|panscan"
221 [content="normal|large|children|normal_cc|large_cc|children_cc|forced|director|large_director|children_director"]
222 id="<replaceable>streamid</replaceable>" /&gt;
223 [&lt;stream ... /&gt;]
224 &lt;/subpicture&gt;
225 [&lt;subpicture ... /&gt;]
226 &lt;pgc [entry="title"] [palette="<replaceable>yuvfile|rgbfile</replaceable>"]
227 [pause="<replaceable>seconds</replaceable>|inf"]&gt;
228 &lt;subpicture&gt;
229 [&lt;stream ... /&gt;]
230 &lt;/subpicture&gt;
231 &lt;pre&gt; <replaceable>commands;</replaceable> &lt;/pre&gt;
232 &lt;vob file="<replaceable>file.mpg</replaceable>" [chapters="<replaceable>chapter-list</replaceable>"]
233 [pause="<replaceable>seconds</replaceable>|inf"]&gt;
234 &lt;cell [start="<replaceable>timestamp</replaceable>"] [end="<replaceable>timestamp</replaceable>"]
235 [chapter="1|on|yes" | program="1|on|yes"] [pause="<replaceable>seconds</replaceable>|inf"]&gt;
236 <replaceable>commands;</replaceable>
237 &lt;/cell&gt;
238 &lt;/vob&gt;
239 [&lt;vob ... /&gt;]
240 &lt;button [name="<replaceable>buttonname</replaceable>"]&gt; <replaceable>commands;</replaceable> &lt;/button&gt;
241 [&lt;button ... /&gt;]
242 &lt;post&gt; <replaceable>commands;</replaceable> &lt;/post&gt;
243 &lt;/pgc&gt;
244 [&lt;pgc ... /&gt;]
245 &lt;/menus&gt;
246 [&lt;menus ... /&gt;]
247 &lt;/vmgm&gt;
248 &lt;titleset&gt;
249 &lt;menus [lang="<replaceable>language-code</replaceable>"]&gt;
250 [&lt;video ... /&gt;]
251 [&lt;audio ... /&gt;]
252 &lt;pgc [entry="<replaceable>entries</replaceable>"]
253 [palette="<replaceable>yuvfile|rgbfile</replaceable>"] [pause="<replaceable>seconds</replaceable>|inf"]&gt;
254 [...]
255 &lt;/pgc&gt;
256 [&lt;pgc ... /&gt;]
257 &lt;/menus&gt;
258 [&lt;menus ... /&gt;]
259 &lt;titles&gt;
260 [&lt;video ... /&gt;]
261 [&lt;audio ... /&gt;]
262 &lt;pgc [entry="notitle"] [palette="<replaceable>yuvfile|rgbfile</replaceable>"] [pause="<replaceable>seconds</replaceable>|inf"]&gt;
263 [...]
264 &lt;/pgc&gt;
265 [&lt;pgc ... /&gt;]
266 &lt;/titles&gt;
267 &lt;/titleset&gt;
268 [&lt;titleset ... /&gt;]
269 &lt;/dvdauthor&gt;
270 </synopsis>
271
272 <para>
273 A breakdown of the control file:
274 </para>
275
276 <variablelist>
277
278 <varlistentry><term><literal>&lt;dvdauthor [dest="<replaceable>output-dir</replaceable>"] [jumppad="1|on|yes" | allgprm="1|on|yes"] [format="ntsc|pal"] [provider="<replaceable>provider</replaceable>"]&gt;</literal></term>
279 <listitem><para>
280 Initiates dvdauthor. <literal>dest</literal> denotes the directory where <command>dvdauthor</command> will write the files. This is overridden by the <literal>-o</literal> option. Contains up to one <literal>&lt;vmgm&gt;</literal> tag and any number of <literal>&lt;titleset&gt;</literal>'s.
281 </para></listitem></varlistentry>
282
283 <varlistentry><term><literal>&lt;vmgm&gt;</literal></term><term><literal>&lt;titleset&gt;</literal></term>
284 <listitem><para>Constructs of a VMGM level menu set or a title set.
285 Contains zero or more <literal>&lt;menus&gt;</literal> tags and if a
286 titleset, up to one <literal>&lt;titles&gt;</literal> tag.
287 </para></listitem></varlistentry>
288
289 <varlistentry><term><literal>&lt;menus
290 [lang="<replaceable>language-code</replaceable>"]&gt;</literal></term>
291 <listitem><para>Marks a list of menus with a common language for this VMGM menu
292 set or titleset, called in <command>dvdauthor</command> terminology a
293 "pgcgroup." Contains up to one <literal>&lt;video&gt;</literal> tag,
294 up to one <literal>&lt;audio&gt;</literal> tag, up to one
295 <literal>&lt;subpicture&gt;</literal> tag, and any number of
296 <literal>&lt;pgc&gt;</literal> tags.
297 </para></listitem></varlistentry>
298
299 <varlistentry><term><literal>&lt;titles&gt;</literal></term>
300 <listitem><para>Marks the list of titles for this titleset, called in
301 <command>dvdauthor</command> terminology a "pgcgroup." Contains up to
302 one <literal>&lt;video&gt;</literal> tag, up to eight
303 <literal>&lt;audio&gt;</literal> tags, up to 32
304 <literal>&lt;subpicture&gt;</literal> tags, and any number of
305 <literal>&lt;pgc&gt;</literal> tags.
306 </para></listitem></varlistentry>
307
308 <varlistentry><term><literal>&lt;video [format="ntsc|pal"]
309 [aspect="4:3|16:9"] [resolution="<replaceable>XxY</replaceable>"]
310 [caption="field1|field2"] [widescreen="nopanscan|noletterbox|crop"]
311 /&gt;</literal></term> <listitem><para> Manually configures the video
312 parameters for this pgcgroup. If any of these are not set, then they
313 will be inferred from the source stream. Note that the DVD format
314 only specifically supports 720x480, 704x480, 352x480, and 352x240
315 resolutions for NTSC, and 720x576, 704x576, 352x576, and 352x288
316 resolutions for PAL, but DVD author will accept a wider range of
317 inputs and round up to the nearest size.
318 </para></listitem></varlistentry>
319
320 <varlistentry><term><literal>&lt;audio [format="mp2|ac3|dts|pcm"]
321 [channels="<replaceable>numchannels</replaceable>"]
322 [dolby="surround"] [quant="16bps|20bps|24bps|drc"] [samplerate="48khz|96khz"]
323 [lang="<replaceable>language</replaceable>"]
324 [content="normal|impaired|comments1|comments2"] /&gt;</literal></term>
325 <listitem><para>Manually configures an audio stream for this
326 pgcgroup. List once for each stream. Most parameters are inferred
327 automatically from the source VOBs except for PCM parameters.
328 However, language and content must be manually specified. Note that it is
329 possible to just list the language and content attributes and let
330 <command>dvdauthor</command> fill in the rest.
331 </para></listitem></varlistentry>
332
333 <varlistentry><term><literal>&lt;subpicture
334 [lang="<replaceable>language</replaceable>"]
335 [content="normal|large|children|normal_cc|large_cc|children_cc|forced|director|large_director|children_director"] /&gt;</literal></term>
336 <listitem><para>Manually configures a subpicture/subtitle for this pgcgroup or PGC.
337 At the pgcgroup level, list once for each language. Occurrences at the PGC level
338 don't have <literal>lang</literal> or <literal>content</literal> attributes; they inherit those
339 from the corresponding <literal>&lt;subpicture&gt;</literal> tag at the pgcgroup level.
340 </para></listitem></varlistentry>
341
342 <varlistentry><term><literal>&lt;stream mode="normal|widescreen|letterbox|panscan"
343 id="<replaceable>streamid</replaceable>" /&gt;</literal></term>
344 <listitem><para>Specifies the ID of a stream that is the representation of this
345 subpicture in a particular display mode. This can be specified per-PGC, or
346 pgcgroup-wide.</para></listitem></varlistentry>
347
348 <varlistentry><term><literal>&lt;pgc
349 [entry="<replaceable>entries</replaceable>"]
350 [palette="<replaceable>yuvfile|rgbfile</replaceable>"]
351 [pause="<replaceable>seconds</replaceable>|inf"]&gt;</literal></term>
352 <listitem><para>A PGC is just a fancy term for either a menu or a
353 title. It has a special meaning in the DVD spec so I have retained
354 its use here. PGC's can have commands that get executed before they
355 start playing or after they finish; see <literal>&lt;pre&gt;</literal> and
356 <literal>&lt;post&gt;</literal> tags below.</para>
357
358 <para>If the PGC is a menu, you can specify one or more entries for
359 it. This means that if you press the corresponding button on your DVD
360 remote, then it will go to this menu. For a VMGM level menu, the only
361 choice is <literal>title</literal>, which on my remote corresponds to
362 the <literal>top menu</literal> button. For a titleset level menu,
363 you can use root, subtitle, audio, angle, and ptt. If you want more
364 than one, separate them by a space or a comma. Note that
365 <literal>root</literal> entry is meant for commands that jump from a
366 VMGM level menu to a titleset menu.</para>
367
368 <para>If the PGC is in a titleset, then it is assumed to be a title unless
369 <literal>entry="notitle"</literal> is specified.</para>
370
371 <para>All button and menu masks and all subtitles within a PGC must
372 share the same 16 color palette. If you use <command>spumux</command>
373 to generate the subtitle/subpicture packets, then the color
374 information will be automatically passed to
375 <command>dvdauthor</command>; however, if you use another subtitler or
376 want to have more control over the palette, you can manually specify
377 it with the <literal>palette</literal> attribute. The first 16
378 entries of the file should be the 16 colors of the palette, listed as
379 6 digit hexadecimal numbers representing either the RGB breakdown (if
380 the filename ends in <literal>.rgb</literal> or the YUV breakdown (if
381 the filename does not end in <literal>.rgb</literal>. After that, the
382 button group information can be listed as pairs of 8 digit hexadecimal
383 numbers; up to three button groups may be specified.</para>
384
385 <para>If you have a short video sequence or just want the video to
386 pause at the end, you can use the <literal>pause</literal> attribute
387 to set the number of seconds (as an integer) from 1 to 254. If you
388 want the video to pause indefinitely, use
389 <literal>inf</literal>.</para>
390
391 </listitem></varlistentry>
392
393 <varlistentry><term><literal>&lt;pre&gt; <replaceable>commands;</replaceable> &lt;/pre&gt;</literal></term>
394 <term><literal>&lt;post&gt; <replaceable>commands;</replaceable> &lt;/post&gt;</literal></term>
395 <listitem><para> Sets the commands to execute before or after a PGC
396 plays. It can be used to loop the current video (by having a
397 <literal>&lt;post&gt; jump ... &lt;/post&gt</literal> sequence), or to
398 conditionally skip certain chapters if a flag has been set.
399 </para></listitem></varlistentry>
400
401 <varlistentry><term><literal>&lt;fpc&gt; <replaceable>commands;</replaceable> &lt;/fpc&gt;</literal></term>
402 <listitem><para> Sets the commands to execute when the disk is first
403 put in the player (FPC = First Program Chain). It can be used to jump
404 to a particular menu or initialize registers on startup. If not
405 specified, an implicit one will be created that jumps to the first
406 menu found, or if there is no menu it will jump to the first title..
407 </para></listitem></varlistentry>
408
409 <varlistentry><term><literal>&lt;vob file="<replaceable>file.mpg</replaceable>" [chapters="<replaceable>chapter-list</replaceable>"] [pause="<replaceable>seconds</replaceable>|inf"] /&gt;</literal></term>
410 <listitem><para>
411 Specifies an input video file for a menu or title, with optional chapter points and pause at the end.
412 </para></listitem></varlistentry>
413
414 <varlistentry><term><literal>&lt;cell [start="<replaceable>timestamp</replaceable>"] [end="<replaceable>timestamp</replaceable>"] [chapter="1|on|yes" | program="1|on|yes"] [pause="<replaceable>seconds</replaceable>|inf"]&gt; <replaceable>commands;</replaceable> &lt;/cell&gt;</literal></term>
415 <listitem><para>
416 A more detailed way of specifying marker points in a title. If present, then the containing
417 <literal>&lt;vob&gt;</literal> must not have a <literal>chapters</literal> attribute.
418 A cell can have a VM command attached to it, to be executed when it plays. If the
419 <literal>program</literal> attribute is set, then this cell will be a point that
420 the user can skip to using the prev/next buttons on their DVD player remote. If the
421 <literal>chapter</literal> attribute is set (implies <literal>program</literal> is set
422 as well), then this cell is also a chapter point.
423 </para></listitem></varlistentry>
424
425 <varlistentry><term><literal>&lt;button [name="<replaceable>buttonname</replaceable>"]&gt; <replaceable>commands;</replaceable> &lt;/button&gt;</literal></term>
426 <listitem><para>
427 Specifies the commands to be executed when the user selects the button with the specified name.
428 You define button names and placements with <command>spumux</command>.
429 </para></listitem></varlistentry>
430
431 </variablelist>
432
433 </refsect1>
434
435 <refsect1><title>Language Description</title>
436 <para>
437 The language is quite simple and roughly looks like C.
438 </para>
439 <itemizedlist>
440 <listitem><para>Statements are terminated with a semicolon.</para></listitem>
441 <listitem><para>Statements can span multiple lines.</para></listitem>
442 <listitem><para>Multiple statements can appear on one line.</para></listitem>
443 <listitem><para>Whitespace (space, tab, newlines) are not important, except to separate keywords and identifiers.</para></listitem>
444 <listitem><para>C-style /* ... */ comments are allowed. Or you can use XML comments
445 &lt;!-- like this --&gt;</para></listitem>
446 </itemizedlist>
447
448 <refsect2><title>Variables</title>
449
450 <para>The DVD virtual machine processes 16 bit values. It supports up
451 to 16 general purpose registers; however <command>dvdauthor</command>
452 reserves 3 for internal use. Thus register 0-12 are available for
453 use and are referred to as <literal>g0</literal> through
454 <literal>g12</literal>.</para>
455
456 <para>There are also 24 system registers, which can be referred to as
457 <literal>s0</literal> through <literal>s23</literal>. Not all of
458 these can be set. Many of these have mnemonic synonyms.</para>
459
460 <glosslist>
461
462 <glossentry><glossterm><literal>audio</literal>
463 (<literal>s1</literal>, rw)</glossterm><glossdef><para>Denotes the
464 audio stream, ranging from 0-7.</para></glossdef></glossentry>
465
466 <glossentry><glossterm><literal>subtitle</literal>
467 (<literal>s2</literal>, rw)</glossterm><glossdef><para>The subtitle
468 track, ranging from 0-31. If you want the subtitle to always be
469 displayed, then you should add 64 (i.e. choose 64-95). Simply
470 selecting the track (0-31) means that only the forced subtitles will
471 be displayed, whereas enabling the track (64-95) means that all the
472 subtitles will be displayed. This allows you to have forced subtitles
473 only for the parts of the movie where the actors are speaking a
474 foreign (to the viewer) language, but still have normal subtitles for
475 the hearing impaired. The hearing impaired viewers would enable the
476 track (64-95) while the other viewers would just select the track
477 (0-31) they would be able to share the
478 track.</para></glossdef></glossentry>
479
480 <glossentry><glossterm><literal>angle</literal>
481 (<literal>s3</literal>, rw)</glossterm><glossdef><para>Selects the
482 angle (currently untested).</para></glossdef></glossentry>
483
484 <glossentry><glossterm><literal>button</literal>
485 (<literal>s8</literal>, rw)</glossterm><glossdef><para>Denotes the
486 currently highlighted button. Note that the value is multiplied by
487 1024, so the first button is 1024, the second is 2048,
488 etc.</para></glossdef></glossentry>
489
490 </glosslist>
491
492 </refsect2>
493
494 <refsect2><title>Expressions</title>
495
496 <para>Expressions follow typical C syntax except that booleans are not
497 convertible to integers and vice versa. Operators and comparisons
498 are:</para>
499
500 <para>
501 <simplelist type="inline" columns="6">
502 <member><literal>==</literal></>
503 <member><literal>!=</literal></>
504 <member><literal>&gt;=</literal></>
505 <member><literal>&gt;</literal></>
506 <member><literal>&lt;=</literal></>
507 <member><literal>&lt;</literal></>
508 <member><literal>&amp;&amp;</literal></>
509 <member><literal>||</literal></>
510 <member><literal>!</literal></>
511 <member><literal>eq</literal></>
512 <member><literal>ne</literal></>
513 <member><literal>ge</literal></>
514 <member><literal>gt</literal></>
515 <member><literal>le</literal></>
516 <member><literal>lt</literal></>
517 <member><literal>and</literal></>
518 <member><literal>or</literal></>
519 <member><literal>xor</literal></>
520 <member><literal>not</literal></>
521 <member><literal>+</literal></>
522 <member><literal>-</literal></>
523 <member><literal>*</literal></>
524 <member><literal>/</literal></>
525 <member><literal>%</literal></>
526 <member><literal>&</literal></>
527 <member><literal>|</literal></>
528 <member><literal>^</literal></>
529 </simplelist>
530 </para>
531
532 <para>Since the code is encapsulated in XML, the parser will catch any
533 unescaped &lt; characters (i.e. not written as "&amp;lt;"), thus alphabetic mnemonics have been
534 provided for all comparison operators for consistency. Or you can put the code
535 in a &lt;![CDATA[ ... ]]&gt; section.</para>
536
537 <para>There is also a numerical function:</para>
538
539 <variablelist>
540
541 <varlistentry><term><literal>random(<replaceable>EXPRESSION</replaceable>)</literal></term>
542 <listitem><para>Computes a pseudo-random number, between 1 and the
543 supplied number, inclusively.</para> </listitem></varlistentry>
544
545 </variablelist>
546
547 </refsect2>
548
549 <refsect2><title>Blocks</title>
550
551 <para>Blocks are either a single statement (terminated by a
552 semicolon), or a group of statements wrapped in curly braces. For
553 example:</para>
554
555 <itemizedlist>
556
557 <listitem><synopsis>g3 = s7;</synopsis></listitem>
558 <listitem><synopsis>{
559 audio = 1;
560 subtitle = 65;
561 jump vmgm menu 3;
562 }</synopsis></listitem>
563
564 </itemizedlist>
565
566 </refsect2>
567
568 <refsect2><title>Statements</title>
569
570 <para>The statements supported are fairly simple at the moment.</para>
571
572 <variablelist>
573
574 <varlistentry>
575 <term><literal><replaceable>VARIABLE</replaceable> = <replaceable>EXPRESSION</replaceable>;</literal></term>
576 <listitem><para>Sets a variable equal to the result of an equation.</para></listitem></varlistentry>
577
578 <varlistentry>
579 <term><literal>if (<replaceable>EXPRESSION</replaceable>) <replaceable>BLOCK;</replaceable></literal></term>
580 <term><literal>if (<replaceable>EXPRESSION</replaceable>) <replaceable>BLOCK;</replaceable> else <replaceable>BLOCK;</replaceable></literal></term>
581
582 <listitem><para>Calculates the expression; if true, then it executes
583 the block of code.</para></listitem></varlistentry>
584
585 <varlistentry><term><literal>jump <replaceable>TARGET</replaceable>;</literal></term>
586 <term><literal>call <replaceable>TARGET</replaceable> [resume <replaceable>CELL</replaceable>];</literal></term>
587 <term><literal>resume;</literal></term>
588
589 <listitem><para>Jumps to a particular title or menu, or calls a
590 particular menu, or returns to the calling title. You can only
591 execute a call from a title to a menu; all other forms are illegal.
592 The purpose of using <literal>call</literal> instead of
593 <literal>jump</literal> (besides the fact that they support a mutually
594 exclusive list of targets) is to allow the menu to return to the point
595 in the title where the call originated using
596 <literal>resume</literal>. You can manually specify the return cell
597 by using the <literal>resume</literal> keyword, however if you do not
598 specify one and you use the command in a post instruction block, then
599 it will presume cell 1.</para>
600 </listitem></varlistentry>
601
602 </variablelist>
603
604 </refsect2>
605
606 <refsect2><title>Targets</title>
607
608 <para>The following are possible targets (note that menus do not have
609 chapters):</para>
610 <variablelist>
611
612 <varlistentry>
613 <term><literal>[vmgm | titleset <replaceable>X</replaceable>] menu</literal></term>
614 <term><literal>[vmgm | titleset <replaceable>X</replaceable>] menu <replaceable>Y</replaceable></literal></term>
615 <term><literal>[vmgm | titleset <replaceable>X</replaceable>] menu entry <replaceable>Z</replaceable></literal></term>
616 <listitem><para>Targets either the default menu, a menu number Y, or the menu denoted as the entry for Z. The menu is in either the VMGM or titleset domain. If you wish to target a menu in the current domain then you can omit the domain moniker.</para></listitem></varlistentry>
617
618 <varlistentry>
619 <term><literal>[titleset <replaceable>X</replaceable>] title <replaceable>Y</replaceable> [chapter <replaceable>Z</replaceable>]</literal></term>
620 <listitem><para>Targets a title, or a chapter in a title. Numbering
621 starts at 1. All of the titles on the disc are accessible in the VMGM
622 domain, or you can access them by titleset
623 instead.</para></listitem></varlistentry>
624
625 <varlistentry>
626 <term><literal>pgc <replaceable>Z</replaceable></literal></term>
627 <listitem><para>Targets a PGC in the current VMGM or titleset.</para></listitem></varlistentry>
628
629 <varlistentry>
630 <term><literal>chapter <replaceable>Z</replaceable></literal></term>
631
632 <listitem><para>Targets a chapter in the current title.</para></listitem></varlistentry>
633
634 <varlistentry>
635 <term><literal>program <replaceable>Z</replaceable></literal></term>
636 <term><literal>cell <replaceable>Z</replaceable></literal></term>
637
638 <listitem><para>Targets a program or cell in the current PGC. You can use
639 this to create looping menus: <literal>jump cell
640 1;</literal></para></listitem></varlistentry>
641
642 <varlistentry>
643 <term><literal>cell top</literal></term>
644 <term><literal>next cell</literal></term>
645 <term><literal>prev cell</literal></term>
646 <term><literal>program top</literal></term>
647 <term><literal>next program</literal></term>
648 <term><literal>prev program</literal></term>
649 <term><literal>pgc top</literal></term>
650 <term><literal>next pgc</literal></term>
651 <term><literal>prev pgc</literal></term>
652 <term><literal>up pgc</literal></term>
653 <term><literal>pgc tail</literal></term>
654 <listitem><para>
655 (Jump only) performs relative transfers of control within the current menu/title.
656 "<literal>cell/program/pgc top</literal>" goes back to the start of the current cell/program/PGC;
657 "<literal>next/prev cell/program/pgc</literal>" goes to the next or previous cell/program/PGC;
658 "<literal>up pgc</literal>" goes to the "up" PGC (not currently settable in
659 <command>dvdauthor</command>); and "<literal>pgc tail</literal>" goes to the
660 <literal>&lt;post&gt;</literal> sequence in the current PGC.
661 </para></listitem></varlistentry>
662
663 </variablelist>
664
665 <para>Chapters are numbered from 1 in each title, while programs are numbered from
666 1 in each PGC. Thus, the latter can reset independently of the former when there is more
667 than one PGC in a title.</para>
668
669 </refsect2>
670
671 </refsect1>
672
673 <refsect1><title>Limitations</title>
674 <para>The following limits are imposed by the DVD-Video spec.</para>
675 <para>There can be no more than 99 titlesets, no more than 99 menus in the VMG
676 or a titleset, and no more than 99 titles in a titleset.</para>
677 <para>Each title may be made up of up to 999 PGCs. Each PGC may consist of up to 255 programs.
678 The <literal>&lt;pre&gt;</literal> and <literal>&lt;post&gt;</literal> sections of a PGC
679 put together can contain no more than 128 VM instructions.</para>
680 <para>Since there is only one VOB file (<literal>VIDEO_TS.VOB</literal>) in the VMG,
681 the total amount of video in the VMG menus must fit into 1073709056 bytes (524272
682 sectors of 2kiB each). In each titleset, all the menu video must fit in the first VOB
683 (<literal>VTS_</literal>nn<literal>_0.VOB</literal>), so is limited to the same amount.</para>
684
685 </refsect1>
686
687 </refentry>