Change/simplify the tableprint/tablegen API.
[ffmpeg.git] / doc / tablegen.txt
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 Due to this, the .c file or Makefile may have to provide additional defines
16 or stubs, though if possible this should be avoided.
17 In particular, CONFIG_HARDCODED_TABLES should always be defined to 0.
18
19 The .c file
20
21 This file should include the *_tablegen.h and tableprint.h files and
22 anything else it needs as long as it does not depend on config.h or
23 avconfig.h.
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
43
44 The .h file
45
46 This file should contain:
47  - one or more initialization functions
48  - the table variable declarations
49 If CONFIG_HARDCODED_TABLES is set, the initialization functions should
50 not do anything, and instead of the variable declarations the
51 generated *_tables.h file should be included.
52 Since that will be generated in the build directory, the path must be
53 included, i.e.
54 #include "libavcodec/example_tables.h"
55 not
56 #include "example_tables.h"
57
58 Makefile changes
59
60 To make the automatic table creation work, you must manually declare the
61 new dependency.
62 For this add a line similar to this:
63 $(SUBDIR)example.o: $(SUBDIR)example_tables.h
64 under the "ifdef CONFIG_HARDCODED_TABLES" section in the Makefile.