Developer Guide Release

GLSLC Shader Program Compiler
Compiled Shader Program Characteristics
Libraries Loaded On-Demand
This section describes glslc, a compiler for OpenGL ES 3.0-style program binaries. This compiler runs on the Linux host system to produce program binaries that can be transferred to the target NVIDIA® Tegra® device.
Program binaries produced with glslc from a particular NVIDIA DRIVE sdk can only be used with the OpenGL ES 3.0 driver from the same NVIDIA DRIVE sdk. Shader sources must be recompiled to generate new program binaries whenever a new sdk is installed.
To compile a shader program
Generate a program binary <output_file> from vertex and fragment shader source files <vertex_shader_file> and <fragment_shader_file> with the following command (on the host system):
glslc -gles -chip 10 -binary <output_file> -vs <vertex_shader_file> -fs <fragment_shader_file>
Shader sources must not contain #include directives. If glslc is successful, it produces a non-zero sized binary named <output file>.
For complete information about additional shader types and supported options for glslc, run the following command:
glslc --help
Compiled Shader Program Characteristics
The resulting program binary only functions correctly with the version of the driver with which the compiler was released.
The format of a compiled program binary is:
4 bytes containing the size of the program binary
4 bytes containing the format of the program binary
A variable number of bytes containing the program data
These should be passed as the 4th, 2nd, and 3rd arguments, respectively, of glProgramBinary. See the gearslib.c file for more details on loading shader programs.
After a successful compilation, glslc displays the following message:
Program binary successfully written to <binary file name>
The size and format of a program binary produced by glslc are expected to match the size and format of a program binary produced by the GL driver via a glGetProgramBinary call.
Libraries Loaded On-Demand
On supported systems, these libraries are only loaded when needed to compile shader programs at runtime:
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.
Systems supporting the on-demand loading of these libraries are the systems used with NVIDIA DRIVE™ Linux sdk and NVIDIA DRIVE™ QNX sdk. See the Release Notes for those releases for specific hardware and software information.
The -driverstate option allows for a small subset of GPU machine microcode to be inserted into the GL program binary via glProgramBinary. In very specific and limited cases, this option can prevent libnvidia-glcore-ocg.so from loading at runtime. GL may optimize 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.
A different -driverstate parameter must be specified for each draw call or glClear call. Multiple -driverstate commands can be input in a single GLSLC command line. The resulting microcode is appended to the same program binary file.
As an example, consider an application utilizing vertex attribute arrays that makes two draw calls, where the state of those arrays changes between each draw call. If attribute array 0 is enabled and attribute array 1 is disabled (constant attribute) during the first draw call, and both arrays are enabled during the second draw call, then the GLSLC command to obtain the program binary with optimized GPU machine code for both these states is similar to the following:
glslc -chip 10 -vs vs.vert -fs fs.frag -binary prog.bin ‑driverstate vertexattribenable 0 -driverstate vertexattribenable 0 vertexattribenable 1
The two -driverstate flags correspond to the state of the driver during each draw call, and there may be multiple vertexattribenable flags for each ‑driverstate usage.
A default set of machine code configurations are included if you use any ‑driverstate flags. Specify an empty -driverstate option followed by no state options if you require a set of default machine code configurations.
For example, the following produces a binary with a default set of machine code:
glslc -chip 10 -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 10 -vs vert.vs -fs frag.fs -driverstate -driverstate vertexattribenable 0
The following is all that is needed:
glslc -chip 10 -vs vert.vs -fs frag.fs -driverstate vertexattribenable 0
The available options are currently limited to vertex and fragment shaders with a limited subset of options for producing the machine code. If the required microcode is not a part of the program binary during runtime, then the libnvidia-glcore-ocg.so library is loaded to perform runtime compilation.