[deb_ffmpeg.git] / ffmpeg / doc / tablegen.txt

Writing a table generator

This documentation is preliminary.
Parts of the API are not good and should be changed.

Basic concepts

A table generator consists of two files, *_tablegen.c and *_tablegen.h.
The .h file will provide the variable declarations and initialization
code for the tables, the .c calls the initialization code and then prints
the tables as a header file using the tableprint.h helpers.
Both of these files will be compiled for the host system, so to avoid
breakage with cross-compilation neither of them may include, directly
or indirectly, config.h or avconfig.h.
This means that e.g. libavutil/mathematics.h is ok but libavutil/libm.h is not.
Due to this, the .c file or Makefile may have to provide additional defines
or stubs, though if possible this should be avoided.
In particular, CONFIG_HARDCODED_TABLES should always be defined to 0.

The .c file

This file should include the *_tablegen.h and tableprint.h files and
anything else it needs as long as it does not depend on config.h or
avconfig.h.
In addition to that it must contain a main() function which initializes
all tables by calling the init functions from the .h file and then prints
them.
The printing code typically looks like this:
    write_fileheader();
    printf("static const uint8_t my_array[100] = {\n");
    write_uint8_t_array(my_array, 100);
    printf("};\n");

This is the more generic form, in case you need to do something special.
Usually you should instead use the short form:
    write_fileheader();
    WRITE_ARRAY("static const", uint8_t, my_array);

write_fileheader() adds some minor things like a "this is a generated file"
comment and some standard includes.
tablegen.h defines some write functions for one- and two-dimensional arrays
for standard types - they print only the "core" parts so they are easier
to reuse for multi-dimensional arrays so the outermost {} must be printed
separately.
If there's no standard function for printing the type you need, the
WRITE_1D_FUNC_ARGV macro is a very quick way to create one.
See libavcodec/dv_tablegen.c for an example.


The .h file

This file should contain:
 - one or more initialization functions
 - the table variable declarations
If CONFIG_HARDCODED_TABLES is set, the initialization functions should
not do anything, and instead of the variable declarations the
generated *_tables.h file should be included.
Since that will be generated in the build directory, the path must be
included, i.e.
#include "libavcodec/example_tables.h"
not
#include "example_tables.h"

Makefile changes

To make the automatic table creation work, you must manually declare the
new dependency.
For this add a line similar to this:
$(SUBDIR)example.o: $(SUBDIR)example_tables.h
under the "ifdef CONFIG_HARDCODED_TABLES" section in the Makefile.
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.