PXL, the Pixel eXpression Language
 
 
 

The following section outlines the traits inherent to the PXL 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:

NoteThe PXL tool can perform point and gather operations, but not scatter operations.

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:

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.

NotePXL does not support vectors, arrays, or matrices.

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.

NoteOperations on color / vec4 are done on a per-channel basis.

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 many alphanumeric characters or underscore character. It must not contain any white spaces.

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

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 Toxik. “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.

NoteIn the following table, all references to type color also refer to vec4, and vice versa.

Interface with Toxik Executable

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

If no function header is present for main(), Toxik 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 Toxik Retimer or Time Offset tools before inputting images to the PXL tool.