Commit | Line | Data |
---|---|---|
2ba45a60 DM |
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_t_array(my_array, 100); | |
32 | printf("};\n"); | |
33 | ||
34 | 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 | 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 | ||
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. |