Chapter 1. Running the Compiler With a Template

Templates are fairly simple, and all run in the same general way: you run the compiler with a predefined 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.

For Users of InfiniteReality

Before continuing: have you considered hardware-based static resizing? With InfiniteReality graphics hardware, you may be able to save the trouble of using a template or creating a new video format. Instead, it may be possible to use 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 online book has a great example of how you can use this feature.

Template Overview

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 through 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.

The Way Templates Work

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


The command-line option for passing arguments to cpp is -p. You will read more about this in “Compiler Options”.

Template Location

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/.

Writing Your Own Template

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.

How to Use the Compiler With Templates

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).

Compiler Options

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”.

Passing Parameters to the Template

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, enter 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 is the best example of its own use. However, for a contrived example, presume the following:

  • The name of the template is GoodTemplate.vfs.

  • The rules files are sampleboard.def and samplechip.def.

  • The template has two variables: VBL_A and VBL_B. These are assigned the values 3 and 4, respectively.

  • The output object file (specified with the -o vfc option) will be MyFile.vfo.

To create the file, enter the following:

/usr/sbin/vfc -p "-DVBL_A=3 -DVBL_B=4" \
-c chip=samplechip.def,board=sampleboard.def \
-o MyFile.vfo \

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.