Templates are pretty simple, and all run in the same general way: you run the compiler with a pre-defined format whose values you supply on the command line. The compiler replaces the variables in its template format with the values you supply and builds the format.
Before continuing: have you considered hardware-based static resizing? With InfiniteReality™ graphics hardware, you may be able to save the trouble of creating a new video format by using a standard output format. If you need only to reduce the resolution (the size of the format in lines and pixels) from one of the standard formats, you can instead use the ircombine(1G) tool to select a frame buffer size different from the monitor displays; the hardware takes care of the rest, magnifying the pixels in the frame buffer to the resolution of the monitor.
The ircombine on-line book has a great example of how you can use this feature.
A template is a normal video format source file whose most important values have been left blank. When you use the template, you specify those values via a parameter on the command line when you run the compiler. On the command line, you use the name of the parameter, assigning the value to it.
There is no formal support in the video format compiler at all for templates: everything is performed via cpp(1) substitution. Because the compiler uses cpp to process its files and because the compiler allows you to specify cpp arguments on its command line, you simply perform normal cpp assignments, such as
-DLINES_PER_FRAME=1024 |
The command-line option for passing arguments to cpp is -p. You will read more about this in “Compiler Options”.
You can use the standard system template that is shipped with the video format compiler (see Chapter 2, “Using the Block Sync Template”) or you can write your own template. Standard templates are stored in the directory /usr/gfx/ucode/common/vfc/vfs/.
If you will be writing many formats of the same kind, a template may be a shortcut for you:
You can eliminate simple cut-and-paste errors by using one debugged format into which you can replace variables.
You can control a master template that others can use from a simple Makefile.
You execute the video format compiler via a standard UNIX shell command line. The compiler has several options which are described in full in the man page (reference page) vfc(1).
Besides specifying parameters, the most important options specify the board and chip configuration for which you are targeting the output. For information on the board and chip specification, see “Specifying Rule Sets”.
To specify parameters that are passed to the template, use the -p option to specify an option to be passed directly to cpp (see “How to Use the Compiler With Templates” for information on parameters). For example, to pass the -DLINES_PER_FRAME=1024 option to cpp, use the following:
/usr/sbin/vfc -p "-DLINES_PER_FRAME=1024" ... |
Be certain to surround the text with quotes; this keeps vfc from interpreting the option instead of passing it to cpp.
The individual template has the best example of its own use. However, for a contrived example, presume the following:
To create the file, use the following command:
/usr/sbin/vfc -p "-DVBL_A=3 -DVBL_B=4" \ -c chip=samplechip.def,board=sampleboard.def \ -o MyFile.vfo \ /usr/gfx/ucode/common/vfc/vfs/GoodTemplate.vfs |
Although this example is available as part of the compiler installation and works as written, it will not create an object file that you can use with hardware—the examples are provided solely to permit practice of syntax. To use real hardware, you must use the rules files shipped with that hardware; you must specify the name of a legitimate template to create a meaningful format.