glShaderBinary
3G

# 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

## Copyright

Copyright 2008 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.