GLSLC Shader Program Compiler

This topic describes glslc, a compiler for OpenGL® ES 3.0 program binaries. This compiler runs on the Linux host system to produce program binaries that can be transferred to the target NVIDIA® Jetson™ device.

Note

glslc produces program binaries for a particular OpenGL ES driver. Compiled shaders and other programs must be recompiled whenever a new driver is installed.

To compile a shader program

  • Enter the following command on the host system:

    $ glslc -gles -chip <chip_id> -binary <output_file> -vs <vertex_shader_file> -fs <fragment_shader_file>

    Where:

    • <chip_id> is a code that indicates the type of processor in the Jetson device:

      Module

      Processor

      <chip_id>

      NVIDIA® Jetson AGX Orin™

      T234

      ga10b

      NVIDIA® Jetson Xavier™ NX series

      T194

      T194

      gv11b

      gv11b

      NVIDIA® Jetson AGX Xavier™ series

    • <output_file> is the pathname of a file to which the compiled binaries are to be written.

    • <vertex_shader_file> and <fragment_shader_file> are respectively the vertex and fragment shader source files.

The shader source files may not contain #include directives.

Note

To display complete information about additional shader types and supported options for glslc, enter the command:

$ glslc --help

Compiled Shader Program Characteristics

The format of a compiled program binary is:

  • Four bytes containing the size of the program binary

  • Four bytes containing the format of the program binary

  • A variable number of bytes containing the compiled program

You pass these parts to the OpenGL ES driver in a call to glProgramBinary(). The second parameter is the format of the program binary, the third is a pointer to it, and the second is the number of bytes in it. For more information about loading shader programs, see the file gearslib.c.

After a successful compilation, glslc displays the message:

Program binary successfully written to <output_file>

The size and format of a program binary produced by glslc should match those of a program binary produced by the OpenGL driver via a call to glGetProgramBinary().

Libraries Loaded on Demand

Two libraries are loaded only when needed to compile shader programs at runtime:

libnvidia-glcore-cg.so.<version>
libnvidia-glcore-ocg.so.<version>

If all of the program binaries used by the application are precompiled, the OpenGL ES driver does not invoke the compiler, and the libraries are not loaded. Also, if the system supports the shader disk cache and the required shaders are found there (usually after the first time the application is run), the libraries are not loaded.

The glslc command’s -driverstate option allows a small subset of GPU machine microcode to be inserted into the OpenGL program binary via glProgramBinary(). In very specific and limited cases, this can prevent libnvidia-glcore-ocg.so from loading at runtime. OpenGL may optimize such machine code depending on the driver state, requiring a new machine code binary to be generated depending on certain states of the driver for each draw call.

You can enter multiple -driverstate options in a single glslc command. You must enter a -driverstate option for each draw call or glClear() call. The resulting microcode is appended to the program binary file (to <output_file>).

As an example, consider an application that utilizes vertex attribute arrays and makes two draw calls, where the state of the arrays changes between draw calls. If attribute array 0 is enabled and attribute array 1 is disabled (the “constant” attribute I set) during the first draw call, and both arrays are enabled during the second draw call, then a glslc command to obtain a binary with optimized GPU machine code for both of those states resembles this:

$ glslc -chip <chip_id> -vs vs.vert -fs fs.frag -binary prog.bin -driverstate vertexattribenable 0 -driverstate vertexattribenable 0 vertexattribenable 1

The two -driverstate flags vertexattribenable and vertexattribenable correspond to the state of the driver during the two draw calls. A glslc command may specify multiple -driverstate options that set the same flags to different values or the same value.

A default set of machine code configurations is included if you use any -driverstate flags. Specify an empty -driverstate option (one followed by no flags) if you need a set of default machine code configurations.

For example, this command produces a binary with a default set of machine code:

$ glslc -chip <chip_id> -vs vert.vs -fs frag.fs -driverstate

You do not need an empty --driverstate option to include the defaults. The defaults are included if you use a --driverstate flag of any kind.

For example, the first -driverstate option below is redundant:

$ glslc -chip <chip_id> -vs vert.vs -fs frag.fs -driverstate -driverstate vertexattribenable 0

This is sufficient:

$ glslc -chip <chip_id> -vs vert.vs -fs frag.fs -driverstate vertexattribenable 0

Note

The available flags are currently limited to vertex and fragment shaders with a limited subset of flags for producing the machine code. If the required microcode is not a part of the program binary during runtime, then the driver loads libnvidia-glcore-ocg.so to perform compilation.