yading@10: Writing a table generator
yading@10: 
yading@10: This documentation is preliminary.
yading@10: Parts of the API are not good and should be changed.
yading@10: 
yading@10: Basic concepts
yading@10: 
yading@10: A table generator consists of two files, *_tablegen.c and *_tablegen.h.
yading@10: The .h file will provide the variable declarations and initialization
yading@10: code for the tables, the .c calls the initialization code and then prints
yading@10: the tables as a header file using the tableprint.h helpers.
yading@10: Both of these files will be compiled for the host system, so to avoid
yading@10: breakage with cross-compilation neither of them may include, directly
yading@10: or indirectly, config.h or avconfig.h.
yading@10: This means that e.g. libavutil/mathematics.h is ok but libavutil/libm.h is not.
yading@10: Due to this, the .c file or Makefile may have to provide additional defines
yading@10: or stubs, though if possible this should be avoided.
yading@10: In particular, CONFIG_HARDCODED_TABLES should always be defined to 0.
yading@10: 
yading@10: The .c file
yading@10: 
yading@10: This file should include the *_tablegen.h and tableprint.h files and
yading@10: anything else it needs as long as it does not depend on config.h or
yading@10: avconfig.h.
yading@10: In addition to that it must contain a main() function which initializes
yading@10: all tables by calling the init functions from the .h file and then prints
yading@10: them.
yading@10: The printing code typically looks like this:
yading@10:     write_fileheader();
yading@10:     printf("static const uint8_t my_array[100] = {\n");
yading@10:     write_uint8_t_array(my_array, 100);
yading@10:     printf("};\n");
yading@10: 
yading@10: This is the more generic form, in case you need to do something special.
yading@10: Usually you should instead use the short form:
yading@10:     write_fileheader();
yading@10:     WRITE_ARRAY("static const", uint8_t, my_array);
yading@10: 
yading@10: write_fileheader() adds some minor things like a "this is a generated file"
yading@10: comment and some standard includes.
yading@10: tablegen.h defines some write functions for one- and two-dimensional arrays
yading@10: for standard types - they print only the "core" parts so they are easier
yading@10: to reuse for multi-dimensional arrays so the outermost {} must be printed
yading@10: separately.
yading@10: If there's no standard function for printing the type you need, the
yading@10: WRITE_1D_FUNC_ARGV macro is a very quick way to create one.
yading@10: See libavcodec/dv_tablegen.c for an example.
yading@10: 
yading@10: 
yading@10: The .h file
yading@10: 
yading@10: This file should contain:
yading@10:  - one or more initialization functions
yading@10:  - the table variable declarations
yading@10: If CONFIG_HARDCODED_TABLES is set, the initialization functions should
yading@10: not do anything, and instead of the variable declarations the
yading@10: generated *_tables.h file should be included.
yading@10: Since that will be generated in the build directory, the path must be
yading@10: included, i.e.
yading@10: #include "libavcodec/example_tables.h"
yading@10: not
yading@10: #include "example_tables.h"
yading@10: 
yading@10: Makefile changes
yading@10: 
yading@10: To make the automatic table creation work, you must manually declare the
yading@10: new dependency.
yading@10: For this add a line similar to this:
yading@10: $(SUBDIR)example.o: $(SUBDIR)example_tables.h
yading@10: under the "ifdef CONFIG_HARDCODED_TABLES" section in the Makefile.