Statistics
| Branch: | Revision:

ffmpeg / doc / tablegen.txt @ 6785e927

History | View | Annotate | Download (2.53 KB)

1
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
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
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
This means that e.g. libavutil/mathematics.h is ok but libavutil/libm.h is not.
16
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
In particular, CONFIG_HARDCODED_TABLES should always be defined to 0.
19

    
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
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
    write_uint8_array(my_array, 100);
32
    printf("};\n");
33

    
34
write_fileheader() adds some minor things like a "this is a generated file"
35
comment and some standard includes.
36
tablegen.h defines some write functions for one- and two-dimensional arrays
37
for standard types - they print only the "core" parts so they are easier
38
to reuse for multi-dimensional arrays so the outermost {} must be printed
39
separately.
40
If there's no standard function for printing the type you need, the
41
WRITE_1D_FUNC_ARGV macro is a very quick way to create one.
42
See libavcodec/dv_tablegen.c for an example.
43

    
44

    
45
The .h file
46

    
47
This file should contain:
48
 - one or more initialization functions
49
 - the table variable declarations
50
If CONFIG_HARDCODED_TABLES is set, the initialization functions should
51
not do anything, and instead of the variable declarations the
52
generated *_tables.h file should be included.
53
Since that will be generated in the build directory, the path must be
54
included, i.e.
55
#include "libavcodec/example_tables.h"
56
not
57
#include "example_tables.h"
58

    
59
Makefile changes
60

    
61
To make the automatic table creation work, you must manually declare the
62
new dependency.
63
For this add a line similar to this:
64
$(SUBDIR)example.o: $(SUBDIR)example_tables.h
65
under the "ifdef CONFIG_HARDCODED_TABLES" section in the Makefile.