1Writing a table generator 2 3This documentation is preliminary. 4Parts of the API are not good and should be changed. 5 6Basic concepts 7 8A table generator consists of two files, *_tablegen.c and *_tablegen.h. 9The .h file will provide the variable declarations and initialization 10code for the tables, the .c calls the initialization code and then prints 11the tables as a header file using the tableprint.h helpers. 12Both of these files will be compiled for the host system, so to avoid 13breakage with cross-compilation neither of them may include, directly 14or indirectly, config.h or avconfig.h. 15This means that e.g. libavutil/mathematics.h is ok but libavutil/libm.h is not. 16Due to this, the .c file or Makefile may have to provide additional defines 17or stubs, though if possible this should be avoided. 18In particular, CONFIG_HARDCODED_TABLES should always be defined to 0. 19 20The .c file 21 22This file should include the *_tablegen.h and tableprint.h files and 23anything else it needs as long as it does not depend on config.h or 24avconfig.h. 25In addition to that it must contain a main() function which initializes 26all tables by calling the init functions from the .h file and then prints 27them. 28The 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 34This is the more generic form, in case you need to do something special. 35Usually you should instead use the short form: 36 write_fileheader(); 37 WRITE_ARRAY("static const", uint8_t, my_array); 38 39write_fileheader() adds some minor things like a "this is a generated file" 40comment and some standard includes. 41tablegen.h defines some write functions for one- and two-dimensional arrays 42for standard types - they print only the "core" parts so they are easier 43to reuse for multi-dimensional arrays so the outermost {} must be printed 44separately. 45If there's no standard function for printing the type you need, the 46WRITE_1D_FUNC_ARGV macro is a very quick way to create one. 47See libavcodec/dv_tablegen.c for an example. 48 49 50The .h file 51 52This file should contain: 53 - one or more initialization functions 54 - the table variable declarations 55If CONFIG_HARDCODED_TABLES is set, the initialization functions should 56not do anything, and instead of the variable declarations the 57generated *_tables.h file should be included. 58Since that will be generated in the build directory, the path must be 59included, i.e. 60#include "libavcodec/example_tables.h" 61not 62#include "example_tables.h" 63 64Makefile changes 65 66To make the automatic table creation work, you must manually declare the 67new dependency. 68For this add a line similar to this: 69$(SUBDIR)example.o: $(SUBDIR)example_tables.h 70under the "ifdef CONFIG_HARDCODED_TABLES" section in the Makefile. 71