GLSLC Shader Program Compiler

 
Compiled Shader Program Characteristics
Libraries Loaded on Demand
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 <TBD_glsc_chip_id> -binary <output_file> -vs <vertex_shader_file> -fs <fragment_shader_file>
Where:
• <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 the fourth, second, and third arguments of in the glProgramBinary(), respectively. 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 switch 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 switches in a single glslc command. You must enter a ‑driverstate switch 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 <TBD_glsc_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 switches that set the same flagsto 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 switch (one followed by noflags) 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 <TBD_glsc_chip_id> ‑vs vert.vs ‑fs frag.fs ‑driverstate
You do not need an empty ‑driverstate switch to include the defaults. The defaults are included if you use a ‑driverstate flag of any kind.
For example, the first ‑driverstate switch below is redundant:
glslc ‑chip <TBD_glsc_chip_id> ‑vs vert.vs ‑fs frag.fs ‑driverstate ‑driverstate vertexattribenable 0
This is sufficient:
glslc ‑chip <TBD_glsc_chip_id> ‑vs vert.vs ‑fs frag.fs ‑driverstate vertexattribenable 0
 
Note:
The available flagsare 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 runtime compilation.