Statistics
| Branch: | Revision:

ffmpeg / doc / tablegen.txt @ 617d56ca

History | View | Annotate | Download (2.73 KB)

1 4f798a6a Reimar Döffinger
Writing a table generator
2
3
This documentation is preliminary.
4
Parts of the API are not good and should be changed.
5
6
Basic concepts
7
8
A table generator consists of two files, *_tablegen.c and *_tablegen.h.
9
The .h file will provide the variable declarations and initialization
10 8eaa6e0e Reimar Döffinger
code for the tables, the .c calls the initialization code and then prints
11
the tables as a header file using the tableprint.h helpers.
12 4f798a6a Reimar Döffinger
Both of these files will be compiled for the host system, so to avoid
13
breakage with cross-compilation neither of them may include, directly
14
or indirectly, config.h or avconfig.h.
15 6785e927 Reimar Döffinger
This means that e.g. libavutil/mathematics.h is ok but libavutil/libm.h is not.
16 4f798a6a Reimar Döffinger
Due to this, the .c file or Makefile may have to provide additional defines
17
or stubs, though if possible this should be avoided.
18 8eaa6e0e Reimar Döffinger
In particular, CONFIG_HARDCODED_TABLES should always be defined to 0.
19 4f798a6a Reimar Döffinger
20
The .c file
21
22
This file should include the *_tablegen.h and tableprint.h files and
23
anything else it needs as long as it does not depend on config.h or
24
avconfig.h.
25 8eaa6e0e Reimar Döffinger
In addition to that it must contain a main() function which initializes
26
all tables by calling the init functions from the .h file and then prints
27
them.
28
The printing code typically looks like this:
29
    write_fileheader();
30
    printf("static const uint8_t my_array[100] = {\n");
31 c9f789ef Reimar Döffinger
    write_uint8_t_array(my_array, 100);
32 8eaa6e0e Reimar Döffinger
    printf("};\n");
33
34 c9f789ef Reimar Döffinger
This is the more generic form, in case you need to do something special.
35
Usually you should instead use the short form:
36
    write_fileheader();
37
    WRITE_ARRAY("static const", uint8_t, my_array);
38
39 8eaa6e0e Reimar Döffinger
write_fileheader() adds some minor things like a "this is a generated file"
40
comment and some standard includes.
41
tablegen.h defines some write functions for one- and two-dimensional arrays
42
for standard types - they print only the "core" parts so they are easier
43
to reuse for multi-dimensional arrays so the outermost {} must be printed
44
separately.
45
If there's no standard function for printing the type you need, the
46
WRITE_1D_FUNC_ARGV macro is a very quick way to create one.
47
See libavcodec/dv_tablegen.c for an example.
48
49 4f798a6a Reimar Döffinger
50
The .h file
51
52
This file should contain:
53
 - one or more initialization functions
54
 - the table variable declarations
55
If CONFIG_HARDCODED_TABLES is set, the initialization functions should
56
not do anything, and instead of the variable declarations the
57
generated *_tables.h file should be included.
58
Since that will be generated in the build directory, the path must be
59
included, i.e.
60
#include "libavcodec/example_tables.h"
61
not
62
#include "example_tables.h"
63
64
Makefile changes
65
66
To make the automatic table creation work, you must manually declare the
67
new dependency.
68
For this add a line similar to this:
69
$(SUBDIR)example.o: $(SUBDIR)example_tables.h
70
under the "ifdef CONFIG_HARDCODED_TABLES" section in the Makefile.