Originally committed as revision 22722 to svn://svn.ffmpeg.org/ffmpeg/trunk
Unified · Split
| @@ -0,0 +1,57 @@ | ||
| 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 describes the tables so they can be printed | |
| 11 | +as a header file. | |
| 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 | + | |
| 18 | +The .c file | |
| 19 | + | |
| 20 | +This file should include the *_tablegen.h and tableprint.h files and | |
| 21 | +anything else it needs as long as it does not depend on config.h or | |
| 22 | +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 | |
| 36 | + | |
| 37 | +The .h file | |
| 38 | + | |
| 39 | +This file should contain: | |
| 40 | + - one or more initialization functions | |
| 41 | + - the table variable declarations | |
| 42 | +If CONFIG_HARDCODED_TABLES is set, the initialization functions should | |
| 43 | +not do anything, and instead of the variable declarations the | |
| 44 | +generated *_tables.h file should be included. | |
| 45 | +Since that will be generated in the build directory, the path must be | |
| 46 | +included, i.e. | |
| 47 | +#include "libavcodec/example_tables.h" | |
| 48 | +not | |
| 49 | +#include "example_tables.h" | |
| 50 | + | |
| 51 | +Makefile changes | |
| 52 | + | |
| 53 | +To make the automatic table creation work, you must manually declare the | |
| 54 | +new dependency. | |
| 55 | +For this add a line similar to this: | |
| 56 | +$(SUBDIR)example.o: $(SUBDIR)example_tables.h | |
| 57 | +under the "ifdef CONFIG_HARDCODED_TABLES" section in the Makefile. | |