mathematics.h no longer needs config.h, so update tablegen code and
[ffmpeg.git] / doc / tablegen.txt
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_array(my_array, 100);
32     printf("};\n");
33
34 write_fileheader() adds some minor things like a "this is a generated file"
35 comment and some standard includes.
36 tablegen.h defines some write functions for one- and two-dimensional arrays
37 for standard types - they print only the "core" parts so they are easier
38 to reuse for multi-dimensional arrays so the outermost {} must be printed
39 separately.
40 If there's no standard function for printing the type you need, the
41 WRITE_1D_FUNC_ARGV macro is a very quick way to create one.
42 See libavcodec/dv_tablegen.c for an example.
43
44
45 The .h file
46
47 This file should contain:
48  - one or more initialization functions
49  - the table variable declarations
50 If CONFIG_HARDCODED_TABLES is set, the initialization functions should
51 not do anything, and instead of the variable declarations the
52 generated *_tables.h file should be included.
53 Since that will be generated in the build directory, the path must be
54 included, i.e.
55 #include "libavcodec/example_tables.h"
56 not
57 #include "example_tables.h"
58
59 Makefile changes
60
61 To make the automatic table creation work, you must manually declare the
62 new dependency.
63 For this add a line similar to this:
64 $(SUBDIR)example.o: $(SUBDIR)example_tables.h
65 under the "ifdef CONFIG_HARDCODED_TABLES" section in the Makefile.