glShaderBinary

Name

glShaderBinary — load a precompiled shader binary

C Specification

void glShaderBinary( GLsizei n,
const GLuint *shaders,
GLenum binaryformat,
const void *binary,
GLsizei length);

Parameters

n
Specifies the number of shader object handles present in shaders.

shaders
Specifies a pointer to an array of shader object handles into which the shader binary will be loaded.

binaryformat
Specifies the shader binary format.

binary
Specifies a pointer to the shader binary data in client memory.

length
Specifies the length of the shader binary data in bytes.

Description

For implementations that support them, glShaderBinary loads precompiled shader binaries. shaders contains a list of n shader object handles. Each handle refers to a unique shader type (vertex shader or fragment shader). binary points to precompiled binary shader code in client memory, and binaryformat denotes the format of the pre-compiled code.

The binary image is decoded according to the extension specification defining the specified binaryformat. OpenGL ES defines no specific binary formats, but does provide a mechanism to obtain symbolic constants for such formats provided by extensions. The number of shader binary formats supported can be obtained by querying the value of GL_NUM_SHADER_BINARY_FORMATS. The list of specific binary formats supported can be obtained by querying the value of GL_SHADER_BINARY_FORMATS.

Depending on the types of the shader objects in shaders, glShaderBinary will individually load binary vertex or fragment shaders, or load an executable binary that contains an optimized pair of vertex and fragment shaders stored in the same binary.

If glShaderBinary fails, the old state of shader objects for which the binary was being loaded will not be restored.

Notes

Shader binary support is optional and thus must be queried before use by calling glGet with arguments GL_NUM_SHADER_BINARY_FORMATS and GL_SHADER_BINARY_FORMATS. glShaderBinary generates GL_INVALID_OPERATION on implementations that do not support any shader binary formats. Such implementations instead offer the glShaderSource alternative for supplying OpenGL ES Shading Language shader source for compilation.

If shader binary formats are supported, then an implementation may require that an optimized pair of vertex and fragment shader binaries that were compiled together to be specified to glLinkProgram. Not specifying an optimized pair my cause glLinkProgram to fail. Such a restriction, if it exists, will be documented in the extension specification defining binaryformat.

OpenGL copies the shader binary data when glShaderBinary is called, so an application may free its copy of the data immediately after the function returns.

Errors

GL_INVALID_ENUM is generated if binaryformat is not a supported format returned in GL_SHADER_BINARY_FORMATS.

GL_INVALID_VALUE is generated if any value in shaders is not a vlue generated by OpenGL.

GL_INVALID_VALUE is generated if the format of the data pointed to by binary does not match binaryformat.

GL_INVALID_VALUE is generated if n or length is negative.

GL_INVALID_OPERATION is generated if any value in shaders is not a shader object, or if there is more than one vertex shader object handle or more than one fragment shader object handle in shaders.

Associated Gets

glGet with arguments GL_NUM_SHADER_BINARY_FORMATS and GL_SHADER_BINARY_FORMATS

glIsShader

See Also

glCreateShader, glDeleteShader, glLinkProgram

中文解释
void glShaderBinary(GLsizei n, const GLuint *shaders, GLenum binaryformat, const void *binary, GLsizei length);

预编译的 shader binary 可以通过 glShaderBinary 这个 API 传给 Shader object, 也就是刚才说的如果 GPU 不支持 compileShader 的话,可以通过这个 API 把 shader binary 传给 shader object。这样会比较省时,节约了 GPU 编译 shader 的时间。 这个函数输入的第一个参数和第二个参数的意思是:shaders 是包含了 n 个 shader object 的数组,每个 shader object 都有自己的类型,比如是 vertex shader 或者是 fragment shader。但是如果 shader 中存放了两个相同类型的 shader,比如存放了两个 vertex shader 的 object,那么就会出现 INVALID_OPERATION 的错误。 第三个参数 binaryformat 指出了预编译 shader 的格式,到时候 shader 会根据 binaryformat 来进行解码,解码后才类似于一个编译好之后的 shader,然后交给 GPU 使用。第四个参数 binary 是一个指向预编译的 shader binary 的指针,第五个参数 length 限定了这个 shader binary 的长度。GPU 支持的 shaderbinary 格式可以由参数 NUM_SHADER_BINARY_FORMATS 和 SHADER_BINARY_FORMATS 查询到, 第一个是用于查询支持的 shader binaryformat 的数量,第二个是查询到具体哪些 shader binaryformat 所被支持。根据 shader 的类型,shaderbinary 会读取 binary vertex 或者 fragment shader。又或者是一个可执行的二进制文件,其中包含了一个优化好的 vertex shader 和 fragment shader 的组合。

这个函数没有输出参数。但是有以下几种情况会出错,除了刚才说到的 shaders 中不能保存两个或者两个以上相同类型的 shader,否则会出现 INVALID_OPERATION 之外,还有比如第一个参数 n 或者最后一个参数 length 为负, 则报INVALID_VALUE,如果第二个参数shaders中保存的shader object不是一个合法的 shader 会报 INVALID_VALUE 的错。第三个参数 binaryformat 如果不被支持, 也就是说不存在于 SHADER_BINARY_FORMATS 之中,那么会出现 INVALID_ENUM 错误。比如第四个参数 binary 指向的数据不符合第三个参数的 binaryformat,那 么会出现 INVALID_VALUE 的错误。并且,可能根据不同的 binaryformat 的定义, 还会出现不同的错误。

如果 glShaderBinary 失败,那么该 shader 的状态不会回滚到编译之前的旧的状态。

需要注意的是,如果 GPU 支持 ShaderBinary 这种机制,那么要求如果 shaderbinary是一组被优化了的vertexshader和fragment shaderbinary,它们必须被用在一起。这种限制一般会写在 binaryformat 的定义文档中。

需要注意的是,有可能某些 GPU 并不支持 glShaderBinary 这种机制,据我所知,这种 GPU 不在少数,那么可以通过 glGet 这个 API,输入 NUM_SHADER_BINARY_FORMATS 和 SHADER_BINARY_FORMATS 这两个参数来查询,假如 GPU 不支持 glShaderBinary 的话,那么执行 glShaderBinary 这个 API 会报 GL_INVALID_OPERATION 的错误。在这种情况下,虽然 GPU 不支持 glShaderBinary,而 shader 又是必不可少的一步,那么这种 GPU 一般都会支持 glShaderSource 和 glCompileShader 那种机制。

GPU 会在我们执行这个 API 的时候就把 shader binary copy 过去了,也就是说, 当执行完这个 API 之后,binary 这个用于保存 shader binary 的指针就可以被 free 了。

Name
glShaderBinary — load pre-compiled shader binaries
C Specification

Parameters
count
Specifies the number of shader object handles contained in shaders.
shaders
Specifies the address of an array of shader handles into which to load pre-compiled shader binaries.
binaryFormat
Specifies the format of the shader binaries contained in binary.
binary
Specifies the address of an array of bytes containing pre-compiled binary shader code.
length
Specifies the length of the array whose address is given in binary.
Description
glShaderBinary loads pre-compiled shader binary code into the count shader objects whose handles are given in shaders. binary points to length bytes of binary shader code stored in client memory. binaryFormat specifies the format of the pre-compiled code.
The binary image contained in binary will be decoded according to the extension specification defining the specified binaryFormat token. OpenGL does not define any specific binary formats, but it does provide a mechanism to obtain token vaues for such formats provided by such extensions.
Depending on the types of the shader objects in shaders, glShaderBinary will individually load binary vertex or fragment shaders, or load an executable binary that contains an optimized pair of vertex and fragment shaders stored in the same binary.
Errors
GL_INVALID_OPERATION is generated if more than one of the handles in shaders refers to the same shader object.
GL_INVALID_ENUM is generated if binaryFormat is not an accepted value.
GL_INVALID_VALUE is generated if the data pointed to by binary does not match the format specified by binaryFormat.
Associated Gets
glGet with parameter GL_NUM_SHADER_BINARY_FORMATS.
glGet with parameter GL_SHADER_BINARY_FORMATS.
Version Support
OpenGL Version

See Also
glGetProgram, glGetProgramBinary, glProgramBinary