Revision 8eaa6e0e doc/tablegen.txt

View differences:

doc/tablegen.txt
7 7

  
8 8
A table generator consists of two files, *_tablegen.c and *_tablegen.h.
9 9
The .h file will provide the variable declarations and initialization
10
code for the tables, the .c describes the tables so they can be printed
11
as a header file.
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 12
Both of these files will be compiled for the host system, so to avoid
13 13
breakage with cross-compilation neither of them may include, directly
14 14
or indirectly, config.h or avconfig.h.
15 15
Due to this, the .c file or Makefile may have to provide additional defines
16 16
or stubs, though if possible this should be avoided.
17
In particular, CONFIG_HARDCODED_TABLES should always be defined to 0.
17 18

  
18 19
The .c file
19 20

  
20 21
This file should include the *_tablegen.h and tableprint.h files and
21 22
anything else it needs as long as it does not depend on config.h or
22 23
avconfig.h.
23
In addition to that it must contain a void tableinit(void) function
24
which initializes all tables by calling the init functions from the .h
25
file.
26
It must also contain a "const struct tabledef tables[]" array describing
27
the tables to be generated.
28
Its entries consist of (in order):
29
 - a string suitable for declaring the table, up to but not including the =
30
   NULL terminates the table
31
 - a function to print the table - tableprint.h defines some defaults,
32
   e.g. write_uint8_array to print a uint8_t array.
33
 - a pointer to the table
34
 - the size of the first dimension of the array
35
 - if applicable, the size of the second dimension of the array
24
In addition to that it must contain a main() function which initializes
25
all tables by calling the init functions from the .h file and then prints
26
them.
27
The printing code typically looks like this:
28
    write_fileheader();
29
    printf("static const uint8_t my_array[100] = {\n");
30
    write_uint8_array(my_array, 100);
31
    printf("};\n");
32

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

  
36 43

  
37 44
The .h file
38 45

  

Also available in: Unified diff