doc: merge syntax.texi, eval.texi and opencl.texi into utils.texi

12 years ago · 949c8627b6
--- a/doc/all-components.texi
+++ b/doc/all-components.texi
@@ -1,9 +1,7 @@
@include config.texi

@ifset config-avutil
@include syntax.texi
@include eval.texi
@include opencl.texi
@include utils.texi
@end ifset

@ifset config-avcodec
--- a/doc/ffmpeg-utils.texi
+++ b/doc/ffmpeg-utils.texi
@@ -17,9 +17,7 @@ by the libavutil library.

@c man end DESCRIPTION

@include syntax.texi
@include eval.texi
@include opencl.texi
@include utils.texi

@chapter See Also

--- a/doc/opencl.texi
+++ b/doc/opencl.texi
@@ -1,22 +0,0 @@
@chapter OpenCL Options
@c man begin OPENCL OPTIONS

 When FFmpeg is configured with @code{--enable-opencl}, it is possible
 to set the options to set in the global OpenCL context. The list of
 supported options follows:

@table @option
@item build_options
 Set build options which used to compiled kernels, see reference "OpenCL Specification Version: 1.2 chapter 5.6.4"

@item platform_idx
 Select platform to run OpenCL code, the platform_idx is the index of platform
 in the device list which can be obtained with av_opencl_get_device_list().

@item device_idx
 Select device to run OpenCL code, the device_idx is the index of device in
 the device list which can be obtained with av_opencl_get_device_list().

@end table

@c man end OPENCL OPTIONS
--- a/doc/syntax.texi
+++ b/doc/syntax.texi
@@ -1,258 +0,0 @@
@chapter Syntax
@c man begin SYNTAX

 This section documents the syntax and formats employed by the FFmpeg
 libraries and tools.

@anchor{quoting_and_escaping}
@section Quoting and escaping

 FFmpeg adopts the following quoting and escaping mechanism, unless
 explicitly specified. The following rules are applied:

@itemize
@item
@code{'} and @code{\} are special characters (respectively used for
 quoting and escaping). In addition to them, there might be other
 special characters depending on the specific syntax where the escaping
 and quoting are employed.

@item
 A special character is escaped by prefixing it with a '\'.

@item
 All characters enclosed between '' are included literally in the
 parsed string. The quote character @code{'} itself cannot be quoted,
 so you may need to close the quote and escape it.

@item
 Leading and trailing whitespaces, unless escaped or quoted, are
 removed from the parsed string.
@end itemize

 Note that you may need to add a second level of escaping when using
 the command line or a script, which depends on the syntax of the
 adopted shell language.

 The function @code{av_get_token} defined in
@file{libavutil/avstring.h} can be used to parse a token quoted or
 escaped according to the rules defined above.

 The tool @file{tools/ffescape} in the FFmpeg source tree can be used
 to automatically quote or escape a string in a script.

@subsection Examples

@itemize
@item
 Escape the string @code{Crime d'Amour} containing the @code{'} special
 character:
@example
 Crime d\'Amour
@end example

@item
 The string above contains a quote, so the @code{'} needs to be escaped
 when quoting it:
@example
 'Crime d'\''Amour'
@end example

@item
 Include leading or trailing whitespaces using quoting:
@example
 '  this string starts and ends with whitespaces  '
@end example

@item
 Escaping and quoting can be mixed together:
@example
 ' The string '\'string\'' is a string '
@end example

@item
 To include a literal @code{\} you can use either escaping or quoting:
@example
 'c:\foo' can be written as c:\\foo
@end example
@end itemize

@anchor{date syntax}
@section Date

 The accepted syntax is:
@example
 [(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
 now
@end example

 If the value is "now" it takes the current time.

 Time is local time unless Z is appended, in which case it is
 interpreted as UTC.
 If the year-month-day part is not specified it takes the current
 year-month-day.

@anchor{time duration syntax}
@section Time duration

 The accepted syntax is:
@example
 [-][HH:]MM:SS[.m...]
 [-]S+[.m...]
@end example

@var{HH} expresses the number of hours, @var{MM} the number a of minutes
 and @var{SS} the number of seconds.

@anchor{video size syntax}
@section Video size
 Specify the size of the sourced video, it may be a string of the form
@var{width}x@var{height}, or the name of a size abbreviation.

 The following abbreviations are recognized:
@table @samp
@item ntsc
 720x480
@item pal
 720x576
@item qntsc
 352x240
@item qpal
 352x288
@item sntsc
 640x480
@item spal
 768x576
@item film
 352x240
@item ntsc-film
 352x240
@item sqcif
 128x96
@item qcif
 176x144
@item cif
 352x288
@item 4cif
 704x576
@item 16cif
 1408x1152
@item qqvga
 160x120
@item qvga
 320x240
@item vga
 640x480
@item svga
 800x600
@item xga
 1024x768
@item uxga
 1600x1200
@item qxga
 2048x1536
@item sxga
 1280x1024
@item qsxga
 2560x2048
@item hsxga
 5120x4096
@item wvga
 852x480
@item wxga
 1366x768
@item wsxga
 1600x1024
@item wuxga
 1920x1200
@item woxga
 2560x1600
@item wqsxga
 3200x2048
@item wquxga
 3840x2400
@item whsxga
 6400x4096
@item whuxga
 7680x4800
@item cga
 320x200
@item ega
 640x350
@item hd480
 852x480
@item hd720
 1280x720
@item hd1080
 1920x1080
@item 2k
 2048x1080
@item 2kflat
 1998x1080
@item 2kscope
 2048x858
@item 4k
 4096x2160
@item 4kflat
 3996x2160
@item 4kscope
 4096x1716
@end table

@anchor{video rate syntax}
@section Video rate

 Specify the frame rate of a video, expressed as the number of frames
 generated per second. It has to be a string in the format
@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
 number or a valid video frame rate abbreviation.

 The following abbreviations are recognized:
@table @samp
@item ntsc
 30000/1001
@item pal
 25/1
@item qntsc
 30000/1001
@item qpal
 25/1
@item sntsc
 30000/1001
@item spal
 25/1
@item film
 24/1
@item ntsc-film
 24000/1001
@end table

@anchor{ratio syntax}
@section Ratio

 A ratio can be expressed as an expression, or in the form
@var{numerator}:@var{denominator}.

 Note that a ratio with infinite (1/0) or negative value is
 considered valid, so you should check on the returned value if you
 want to exclude those values.

 The undefined value can be expressed using the "0:0" string.

@anchor{color syntax}
@section Color

 It can be the name of a color (case insensitive match) or a
 [0x|#]RRGGBB[AA] sequence, possibly followed by "@@" and a string
 representing the alpha component.

 The alpha component may be a string composed by "0x" followed by an
 hexadecimal number or a decimal number between 0.0 and 1.0, which
 represents the opacity value (0x00/0.0 means completely transparent,
 0xff/1.0 completely opaque).
 If the alpha component is not specified then 0xff is assumed.

 The string "random" will result in a random color.

@c man end SYNTAX
--- a/doc/utils.texi
+++ b/doc/utils.texi
@@ -1,3 +1,262 @@
@chapter Syntax
@c man begin SYNTAX

 This section documents the syntax and formats employed by the FFmpeg
 libraries and tools.

@anchor{quoting_and_escaping}
@section Quoting and escaping

 FFmpeg adopts the following quoting and escaping mechanism, unless
 explicitly specified. The following rules are applied:

@itemize
@item
@code{'} and @code{\} are special characters (respectively used for
 quoting and escaping). In addition to them, there might be other
 special characters depending on the specific syntax where the escaping
 and quoting are employed.

@item
 A special character is escaped by prefixing it with a '\'.

@item
 All characters enclosed between '' are included literally in the
 parsed string. The quote character @code{'} itself cannot be quoted,
 so you may need to close the quote and escape it.

@item
 Leading and trailing whitespaces, unless escaped or quoted, are
 removed from the parsed string.
@end itemize

 Note that you may need to add a second level of escaping when using
 the command line or a script, which depends on the syntax of the
 adopted shell language.

 The function @code{av_get_token} defined in
@file{libavutil/avstring.h} can be used to parse a token quoted or
 escaped according to the rules defined above.

 The tool @file{tools/ffescape} in the FFmpeg source tree can be used
 to automatically quote or escape a string in a script.

@subsection Examples

@itemize
@item
 Escape the string @code{Crime d'Amour} containing the @code{'} special
 character:
@example
 Crime d\'Amour
@end example

@item
 The string above contains a quote, so the @code{'} needs to be escaped
 when quoting it:
@example
 'Crime d'\''Amour'
@end example

@item
 Include leading or trailing whitespaces using quoting:
@example
 '  this string starts and ends with whitespaces  '
@end example

@item
 Escaping and quoting can be mixed together:
@example
 ' The string '\'string\'' is a string '
@end example

@item
 To include a literal @code{\} you can use either escaping or quoting:
@example
 'c:\foo' can be written as c:\\foo
@end example
@end itemize

@anchor{date syntax}
@section Date

 The accepted syntax is:
@example
 [(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
 now
@end example

 If the value is "now" it takes the current time.

 Time is local time unless Z is appended, in which case it is
 interpreted as UTC.
 If the year-month-day part is not specified it takes the current
 year-month-day.

@anchor{time duration syntax}
@section Time duration

 The accepted syntax is:
@example
 [-][HH:]MM:SS[.m...]
 [-]S+[.m...]
@end example

@var{HH} expresses the number of hours, @var{MM} the number a of minutes
 and @var{SS} the number of seconds.

@anchor{video size syntax}
@section Video size
 Specify the size of the sourced video, it may be a string of the form
@var{width}x@var{height}, or the name of a size abbreviation.

 The following abbreviations are recognized:
@table @samp
@item ntsc
 720x480
@item pal
 720x576
@item qntsc
 352x240
@item qpal
 352x288
@item sntsc
 640x480
@item spal
 768x576
@item film
 352x240
@item ntsc-film
 352x240
@item sqcif
 128x96
@item qcif
 176x144
@item cif
 352x288
@item 4cif
 704x576
@item 16cif
 1408x1152
@item qqvga
 160x120
@item qvga
 320x240
@item vga
 640x480
@item svga
 800x600
@item xga
 1024x768
@item uxga
 1600x1200
@item qxga
 2048x1536
@item sxga
 1280x1024
@item qsxga
 2560x2048
@item hsxga
 5120x4096
@item wvga
 852x480
@item wxga
 1366x768
@item wsxga
 1600x1024
@item wuxga
 1920x1200
@item woxga
 2560x1600
@item wqsxga
 3200x2048
@item wquxga
 3840x2400
@item whsxga
 6400x4096
@item whuxga
 7680x4800
@item cga
 320x200
@item ega
 640x350
@item hd480
 852x480
@item hd720
 1280x720
@item hd1080
 1920x1080
@item 2k
 2048x1080
@item 2kflat
 1998x1080
@item 2kscope
 2048x858
@item 4k
 4096x2160
@item 4kflat
 3996x2160
@item 4kscope
 4096x1716
@end table

@anchor{video rate syntax}
@section Video rate

 Specify the frame rate of a video, expressed as the number of frames
 generated per second. It has to be a string in the format
@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
 number or a valid video frame rate abbreviation.

 The following abbreviations are recognized:
@table @samp
@item ntsc
 30000/1001
@item pal
 25/1
@item qntsc
 30000/1001
@item qpal
 25/1
@item sntsc
 30000/1001
@item spal
 25/1
@item film
 24/1
@item ntsc-film
 24000/1001
@end table

@anchor{ratio syntax}
@section Ratio

 A ratio can be expressed as an expression, or in the form
@var{numerator}:@var{denominator}.

 Note that a ratio with infinite (1/0) or negative value is
 considered valid, so you should check on the returned value if you
 want to exclude those values.

 The undefined value can be expressed using the "0:0" string.

@anchor{color syntax}
@section Color

 It can be the name of a color (case insensitive match) or a
 [0x|#]RRGGBB[AA] sequence, possibly followed by "@@" and a string
 representing the alpha component.

 The alpha component may be a string composed by "0x" followed by an
 hexadecimal number or a decimal number between 0.0 and 1.0, which
 represents the opacity value (0x00/0.0 means completely transparent,
 0xff/1.0 completely opaque).
 If the alpha component is not specified then 0xff is assumed.

 The string "random" will result in a random color.

@c man end SYNTAX

@chapter Expression Evaluation
@c man begin EXPRESSION EVALUATION

@@ -301,3 +560,26 @@ indication of the corresponding powers of 10 and of 2.
@end table

@c man end

@chapter OpenCL Options
@c man begin OPENCL OPTIONS

 When FFmpeg is configured with @code{--enable-opencl}, it is possible
 to set the options to set in the global OpenCL context. The list of
 supported options follows:

@table @option
@item build_options
 Set build options which used to compiled kernels, see reference "OpenCL Specification Version: 1.2 chapter 5.6.4"

@item platform_idx
 Select platform to run OpenCL code, the platform_idx is the index of platform
 in the device list which can be obtained with av_opencl_get_device_list().

@item device_idx
 Select device to run OpenCL code, the device_idx is the index of device in
 the device list which can be obtained with av_opencl_get_device_list().

@end table

@c man end OPENCL OPTIONS