PXL, the Pixel eXpression Language

Example Script and Procedure

The following example PXL script and procedure multiplies the input pixel R, G, and B components by 3.

To multiply the input pixel R, G, and B components by 3:

1. Add a PXL tool to the dependency graph.
2. Click the Edit button and type the script into the script editor.
   

   The pixels in the image are multiplied by a factor of 3.

Image Processing Algorithm Categories

There are three types of image processing operators: the point operator, the gather operator, and the scatter operator. They are based on a workflow in which there are one or more input images and a single output image:

• Point operator Image processing operation that only reads pixels from the input images at the current position, and only writes one pixel to the output image, at the same position.
• Gather operator Image processing operation that reads pixels from the input images from any position, and only writes one pixel to the output image, at the current position.
• Scatter operator Image processing operation that reads pixels from the input images from any position and writes one or more pixels to the output image at any position.

Fundamental Types

PXL supports a specific set of fundamental types. It is case sensitive. Like C, all the variables must be declared before they can be used in an expression statement, unless the variable is a built-in variable, or a function argument. Unlike the C++ language, it is not possible to define new types with objects or structures. Here is the list of supported fundamental types:

• image
• float
• color/vec4

The color and vec4 types are aliases of one another, and are provided for convenience and readability. Otherwise, they are syntactically identical for PXL, and can be used interchangeably. Any reference in the documentation to type color can be understood as vec4, and vice versa.

The color / vec4 type is a quadruplet of floating point values for R, G, B, and A (or equivalently, X, Y, Z and W). These values are unclamped (even for A), which fully supports high dynamic range scene-referred color manipulation. No explicit type casting or type conversion is supported. However, many mixed-type assignment operators and functions are provided.

If a variable of image type is used where type rules would require a color type, the language automatically calls the built-in single-argument sample (image) function. This is provided as a convenience.

As PXL has no Boolean type, the float type is used to represent Boolean values. Any value that is different from 0.0. PXL Boolean operators return 1.0 as a true value.

Qualifiers

A variable can be defined as const. In this case, the variable cannot be modified after his initialization. An error will be issued if a const variable is modified after initialization.

As previously described, function arguments can be qualified as input or output. These are currently only used by the PXL tool to pass in data to the main() function and read out the output pixel value. The initial value of an output argument is undefined.

Comments

Comments use the same syntax as C. Two consecutive slashes (“// Comment”) are used for starting a single line comment. The slash-star (“/*”) is the beginning token for multi-line comment, while the star-slash (“*/”) is used to stop the multi-line comment.

Control Statement

PXL supports the “if” statement, the “while” statement and the “for” statement. They also use the same syntax as in the C language. The only exceptions are that PXL has no break or continue statements to affect looping.

Operators

PXL supports the following operators, which are a subset of those found in C. Of note are the lack of bitwise manipulation operators, as well as the lack of a modulo operator, however the modulo is available through the built-in mod() function—see Built-in Functions.

Variable Declarations

The naming of variables uses the same rules as C. A variable name must begin with an alphabetical character, followed by none or more alphanumeric characters or underscore character. It must not contain any white spaces.

All variables are initialized by Composite upon declaration, depending on type:

• Float variables are initialized to 0.
• Color / vec4 variables are initialized to (0, 0, 0, 1).
• Image variables are initialized to an uninitialized image. An uninitialized image will return (0, 0, 0, 1) on sample(), has a pixel aspect ratio of 0, and has a size of (0, 0).

Numeric Constants

Built-in Variables

PXL has built-in variables to ease script writing. These variables are “x”, “y”, and “t”. The first two are the floating-point normalized image reference frame (x, y) coordinates of the pixel being computed—see Calculating Image Size in Composite. “t” is the floating-point current time, in seconds. All built-in variables are declared constant by the system, so they cannot be assigned to. PXL exposes the IRF coordinates of each pixel in its x and y built-in variables. This means that in PXL horizontally adjacent pixels will have a value of the x built-in variable that differs by 0.9 for an NTSC image. Thus, an NTSC image (with 720x486 pixels) is actually 648x486 IRF units (720 * 0.9 = 648), which represents a 4:3 image aspect ratio (648/486 = 4/3), as expected.

Built-in Functions

PXL provides a number of built-in functions. Functions can return any of the PXL fundamental types, or can return void. Built-in function argument overloading is supported by the sample() function to provide two implementations, one with a single argument, the other with 3 arguments.

Interface with Composite Executable

The Composite executable interfaces with the PXL script in the following way:

• The function declaration is optional. If present, it must be called “main()”.
• Function arguments can be any of the PXL basic types. Arguments to “main()” of type “image” with the “input” qualifier are the PXL tool image inputs, and must match the name of the input image socket. This implies that accessing the primary image input must be done with an input image argument named “In”. Arguments to “main()” of non-image type with the “input” qualifier are PXL tool parameter inputs, and are matched by name and type with the input parameters of the PXL tool. For example, a float parameter named “Gain” would be passed in the “main()” function as “input float Gain”. Arguments to “main()” of type “color” with the “output” qualifier are the pixel outputs. The first version of the PXL tool supports a single pixel output, which must be called “Out”.
• The return type is limited to void and the return statement is not supported.

If no function header is present for main(), Composite will create one automatically. It will include all defined image inputs, and all defined parameter inputs.

No warning is given if main() function arguments are not referenced by the function. However, a reference to a non-existent parameter or input image is an error.

All images read by the PXL script are read at the current time t. There is no way to read images at a time different from t within a PXL script. To do so, a user must use external Composite Retimer or Time Offset tools before inputting images to the PXL tool.