FFmpeg
textutils.h
Go to the documentation of this file.
1 /*
2  * This file is part of FFmpeg.
3  *
4  * FFmpeg is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * FFmpeg is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with FFmpeg; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  */
18 
19 /**
20  * @file
21  * text utilities
22  */
23 
24 #ifndef AVFILTER_TEXTUTILS_H
25 #define AVFILTER_TEXTUTILS_H
26 
27 #include "libavutil/bprint.h"
28 #include "libavutil/eval.h"
29 #include "libavutil/log.h"
30 #include "libavutil/parseutils.h"
31 
32 /**
33  * Function used to expand a template sequence in the format
34  * %{FUNCTION_NAME[:PARAMS]}, defined in the TextExpander object.
35  */
36 typedef struct FFExpandTextFunction {
37  /**
38  * name of the function
39  */
40  const char *name;
41 
42  /**
43  * minimum and maximum number of arguments accepted by the
44  * function in the PARAMS
45  */
46  unsigned argc_min, argc_max;
47 
48  /**
49  * actual function used to perform the expansion
50  */
51  int (*func)(void *ctx, AVBPrint *bp, const char *function_name, unsigned argc, char **args);
53 
54 /**
55  * Text expander context, used to encapsulate the logic to expand a
56  * given text template.
57  *
58  * A backslash character @samp{\} in a text template, followed by any
59  * character, always expands to the second character.
60  * Sequences of the form %{FUNCTION_NAME[:PARAMS]} are expanded using a
61  * function defined in the object. The text between the braces is a
62  * function name, possibly followed by arguments separated by ':'. If
63  * the arguments contain special characters or delimiters (':' or
64  * '}'), they should be escaped.
65  */
66 typedef struct FFExpandTextContext {
67  /**
68  * log context to pass to the function, used for logging and for
69  * accessing the context for the function
70  */
71  void *log_ctx;
72 
73  /**
74  * list of functions to use to expand sequences in the format
75  * FUNCTION_NAME{PARAMS}
76  */
78 
79  /**
80  * number of functions
81  */
82  unsigned int functions_nb;
84 
85 /**
86  * Expand text template.
87  *
88  * Expand text template defined in text using the logic defined in a text
89  * expander object.
90  *
91  * @param expand_text text expansion context used to expand the text
92  * @param text template text to expand
93  * @param bp BPrint object where the expanded text is written to
94  * @return negative value corresponding to an AVERROR error code in case of
95  * errors, a non-negative value otherwise
96  */
97 int ff_expand_text(FFExpandTextContext *expand_text, const char *text, AVBPrint *bp);
98 
99 /**
100  * Print PTS representation to an AVBPrint object.
101  *
102  * @param log_ctx pointer to av_log object
103  * @param bp AVBPrint object where the PTS textual representation is written to
104  * @param pts PTS value expressed as a double to represent
105  * @param delta delta time parsed by av_parse_time(), added to the PTS
106  * @param fmt string representing the format to use for printing, can be
107  * "flt" - use a float representation with 6 decimal digits,
108  * "hms" - use HH:MM:SS.MMM format,
109  * "hms24hh" - same as "hms" but wraps the hours in 24hh format
110  * (so that it is expressed in the range 00-23),
111  * "localtime" or "gmtime" - expand the PTS according to the
112  * @code{strftime()} function rules, using either the corresponding
113  * @code{localtime()} or @code{gmtime()} time
114  * @param strftime_fmt: @code{strftime()} format to use to represent the PTS in
115  * case the format "localtime" or "gmtime" was selected, if not specified
116  * defaults to "%Y-%m-%d %H:%M:%S"
117  * @return negative value corresponding to an AVERROR error code in case of
118  * errors, a non-negative value otherwise
119  */
120 int ff_print_pts(void *log_ctx, AVBPrint *bp, double pts, const char *delta,
121  const char *fmt, const char *strftime_fmt);
122 
123 /**
124  * Print time representation to an AVBPrint object.
125  *
126  * @param log_ctx pointer to av_log object
127  * @param bp AVBPrint object where the time textual representation is written to
128  * @param strftime_fmt: strftime() format to use to represent the time in case
129  * if not specified defaults to "%Y-%m-%d %H:%M:%S". The format string is
130  * extended to support the %[1-6]N after %S which prints fractions of the
131  * second with optionally specified number of digits, if not specified
132  * defaults to 3.
133  * @param localtime use local time to compute the time if non-zero, otherwise
134  * use UTC
135  * @return negative value corresponding to an AVERROR error code in case of
136  * errors, a non-negative value otherwise
137  */
138 int ff_print_time(void *log_ctx, AVBPrint *bp, const char *strftime_fmt, char localtime);
139 
140 typedef double (*ff_eval_func2)(void *, double a, double b);
141 
142 /**
143  * Evaluate and print expression to an AVBprint object.
144  * The output is written as a double representation.
145  *
146  * This is a wrapper around av_expr_parse_and_eval() and following the
147  * same rules.
148  *
149  * @param log_ctx pointer to av_log object
150  * @param bp AVBPrint object where the evaluated expression is written to
151  * @param expr the expression to be evaluated
152  * @param fun_names names of the ff_eval_func2 functions used to evaluate the expression
153  * @param fun_values values of the ff_eval_func2 functions used to evaluate the expression
154  * @param var_names names of the variables used in the expression
155  * @param var_values values of the variables used in the expression
156  * @param eval_ctx evaluation context to be passed to some functions
157  *
158  * @return negative value corresponding to an AVERROR error code in case of
159  * errors, a non-negative value otherwise
160  */
161 int ff_print_eval_expr(void *log_ctx, AVBPrint *bp,
162  const char *expr,
163  const char * const *fun_names, const ff_eval_func2 *fun_values,
164  const char * const *var_names, const double *var_values,
165  void *eval_ctx);
166 
167 /**
168  * Evaluate and print expression to an AVBprint object, using the
169  * specified format.
170  *
171  * This is a wrapper around av_expr_parse_and_eval() and following the
172  * same rules.
173  *
174  * The format is specified as a printf format character, optionally
175  * preceded by the positions numbers for zero-padding.
176  *
177  * The following formats are accepted:
178  * - x: use lowercase hexadecimal representation
179  * - X: use uppercase hexadecimal representation
180  * - d: use decimal representation
181  * - u: use unsigned decimal representation
182  *
183  * @param log_ctx pointer to av_log object
184  * @param bp AVBPrint object where the evaluated expression is written to
185  * @param expr the expression to be evaluated
186  * @param fun_names names of the ff_eval_func2 functions used to evaluate the expression
187  * @param fun_values values of the ff_eval_func2 functions used to evaluate the expression
188  * @param var_names names of the variables used in the expression
189  * @param var_values values of the variables used in the expression
190  * @param eval_ctx evaluation context to be passed to some functions
191  * @param format a character representing the format, to be chosen in xXdu
192  * @param positions final size of the value representation with 0-padding
193  * @return negative value corresponding to an AVERROR error code in case of
194  * errors, a non-negative value otherwise
195  */
196 int ff_print_formatted_eval_expr(void *log_ctx, AVBPrint *bp,
197  const char *expr,
198  const char * const *fun_names, const ff_eval_func2 *fun_values,
199  const char * const *var_names, const double *var_values,
200  void *eval_ctx,
201  const char format, int positions);
202 
203 /**
204  * Check if the character is a newline.
205  *
206  * @param c character to check
207  * @return non-negative value in case c is a newline, 0 otherwise
208  */
209 static inline int ff_is_newline(uint32_t c)
210 {
211  return c == '\n' || c == '\r' || c == '\f' || c == '\v';
212 }
213 
214 /**
215  * Load text file into the buffer pointed by text.
216  *
217  * @param log_ctx pointer to av_log object
218  * @param textfile filename containing the text to load
219  * @param text pointer to the text buffer where the loaded text will be
220  * loaded
221  * @param text_size pointer to the value to set with the loaded text data,
222  * including the terminating 0 character
223  * @return negative value corresponding to an AVERROR error code in case of
224  * errors, a non-negative value otherwise
225  */
226 int ff_load_textfile(void *log_ctx, const char *textfile,
227  unsigned char **text, size_t *text_size);
228 
229 #endif /* AVFILTER_TEXTUTILS__H */
ff_expand_text
int ff_expand_text(FFExpandTextContext *expand_text, const char *text, AVBPrint *bp)
Expand text template.
Definition: textutils.c:124
b
#define b
Definition: input.c:41
FFExpandTextContext::functions_nb
unsigned int functions_nb
number of functions
Definition: textutils.h:82
positions
const static uint16_t positions[][14][3]
Definition: vf_vectorscope.c:817
FFExpandTextContext::log_ctx
void * log_ctx
log context to pass to the function, used for logging and for accessing the context for the function
Definition: textutils.h:71
pts
static int64_t pts
Definition: transcode_aac.c:644
FFExpandTextFunction
Function used to expand a template sequence in the format %{FUNCTION_NAME[:PARAMS]},...
Definition: textutils.h:36
ff_load_textfile
int ff_load_textfile(void *log_ctx, const char *textfile, unsigned char **text, size_t *text_size)
Definition: textutils.c:354
var_names
static const char *const var_names[]
Definition: noise.c:31
format
Filter the word “frame” indicates either a video frame or a group of audio as stored in an AVFrame structure Format for each input and each output the list of supported formats For video that means pixel format For audio that means channel sample format(the sample packing is implied by the sample format) and sample rate. The lists are not just lists
ctx
AVFormatContext * ctx
Definition: movenc.c:49
FFExpandTextFunction::name
const char * name
name of the function
Definition: textutils.h:40
FFExpandTextContext::functions
const FFExpandTextFunction * functions
list of functions to use to expand sequences in the format FUNCTION_NAME{PARAMS}
Definition: textutils.h:77
ff_print_formatted_eval_expr
int ff_print_formatted_eval_expr(void *log_ctx, AVBPrint *bp, const char *expr, const char *const *fun_names, const ff_eval_func2 *fun_values, const char *const *var_names, const double *var_values, void *eval_ctx, const char format, int positions)
Definition: textutils.c:304
parseutils.h
double
double
Definition: af_crystalizer.c:132
c
Undefined Behavior In the C some operations are like signed integer dereferencing freed accessing outside allocated Undefined Behavior must not occur in a C it is not safe even if the output of undefined operations is unused The unsafety may seem nit picking but Optimizing compilers have in fact optimized code on the assumption that no undefined Behavior occurs Optimizing code based on wrong assumptions can and has in some cases lead to effects beyond the output of computations The signed integer overflow problem in speed critical code Code which is highly optimized and works with signed integers sometimes has the problem that often the output of the computation does not c
Definition: undefined.txt:32
FFExpandTextFunction::argc_min
unsigned argc_min
minimum and maximum number of arguments accepted by the function in the PARAMS
Definition: textutils.h:46
eval.h
ff_print_eval_expr
int ff_print_eval_expr(void *log_ctx, AVBPrint *bp, const char *expr, const char *const *fun_names, const ff_eval_func2 *fun_values, const char *const *var_names, const double *var_values, void *eval_ctx)
Definition: textutils.c:282
a
The reader does not expect b to be semantically here and if the code is changed by maybe adding a a division or other the signedness will almost certainly be mistaken To avoid this confusion a new type was SUINT is the C unsigned type but it holds a signed int to use the same example SUINT a
Definition: undefined.txt:41
FFExpandTextFunction::func
int(* func)(void *ctx, AVBPrint *bp, const char *function_name, unsigned argc, char **args)
actual function used to perform the expansion
Definition: textutils.h:51
ff_print_pts
int ff_print_pts(void *log_ctx, AVBPrint *bp, double pts, const char *delta, const char *fmt, const char *strftime_fmt)
Definition: textutils.c:150
bprint.h
log.h
delta
float delta
Definition: vorbis_enc_data.h:430
FFExpandTextContext
in a text template, followed by any character, always expands to the second character.
Definition: textutils.h:66
FFExpandTextFunction::argc_max
unsigned argc_max
Definition: textutils.h:46
ff_print_time
int ff_print_time(void *log_ctx, AVBPrint *bp, const char *strftime_fmt, char localtime)
Definition: textutils.c:203