avopt: Reorder the default_val struct, making i64 the first field
[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_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.