<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
	      "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glShaderBinary">
    <refmeta>
	<refentrytitle>glShaderBinary</refentrytitle>
	<manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
	<refname>glShaderBinary</refname>
	<refpurpose>load a precompiled shader binary</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
	<funcsynopsis>
	    <funcprototype>
		<funcdef>void <function>glShaderBinary</function></funcdef>
		<paramdef>GLsizei <parameter>n</parameter></paramdef>
		<paramdef>const GLuint *<parameter>shaders</parameter></paramdef>
		<paramdef>GLenum <parameter>binaryformat</parameter></paramdef>
		<paramdef>const void *<parameter>binary</parameter></paramdef>
		<paramdef>GLsizei <parameter>length</parameter></paramdef>
	    </funcprototype>
	</funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters"><title>Parameters</title>
	<variablelist>
	    <varlistentry>
		<term><parameter>n</parameter></term>
		<listitem>
		    <para>Specifies the number of shader object handles
                    present in <parameter>shaders</parameter>.</para>
		</listitem>
	    </varlistentry>
	    <varlistentry>
		<term><parameter>shaders</parameter></term>
		<listitem>
		    <para>Specifies a pointer to an array of shader object handles into
		    which the shader binary will be loaded.</para>
		</listitem>
	    </varlistentry>
	    <varlistentry>
		<term><parameter>binaryformat</parameter></term>
		<listitem>
		    <para>Specifies the shader binary format.</para>
		</listitem>
	    </varlistentry>
	    <varlistentry>
		<term><parameter>binary</parameter></term>
		<listitem>
		    <para>Specifies a pointer to the shader binary data in client memory.</para>
		</listitem>
	    </varlistentry>
	    <varlistentry>
		<term><parameter>length</parameter></term>
		<listitem>
		    <para>Specifies the length of the shader binary data in bytes.</para>
		</listitem>
	    </varlistentry>
	</variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
	<para>For implementations that support them, 
	<function>glShaderBinary</function> loads precompiled shader binaries.
	<parameter>shaders</parameter> contains a list of <parameter>n</parameter>
	shader object handles. Each handle refers to a unique shader type (vertex shader or
	fragment shader). <parameter>binary</parameter> points to precompiled binary
	shader code in client memory, and <parameter>binaryformat</parameter> denotes
	the format of the pre-compiled code.</para>

	<para>The binary image is decoded according to the extension
	specification defining the specified <parameter>binaryformat</parameter>.
	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 <constant>GL_NUM_SHADER_BINARY_FORMATS</constant>. The list of
	specific binary formats supported can be obtained by querying the value of
	<constant>GL_SHADER_BINARY_FORMATS</constant>.</para>

	<para>Depending on the types of the shader objects in <parameter>shaders</parameter>,
	<function>glShaderBinary</function> 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.</para>

	<para>If <function>glShaderBinary</function> fails, the old state of shader
	objects for which the binary was being loaded will not be restored.</para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
	<para>Shader binary support is optional and thus must be queried
	before use by calling <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
	with arguments <constant>GL_NUM_SHADER_BINARY_FORMATS</constant> and
	<constant>GL_SHADER_BINARY_FORMATS</constant>. <function>glShaderBinary</function> 
	generates <constant>GL_INVALID_OPERATION</constant> on implementations
	that do not support any shader binary formats. Such implementations instead
        offer the <citerefentry><refentrytitle>glShaderSource</refentrytitle></citerefentry>
	alternative for supplying OpenGL ES Shading Language shader source for compilation.</para>

	<para>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
	<citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>.
	Not specifying an optimized pair my cause 
	<citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>
	to fail. Such a restriction, if it exists, will be documented in
	the extension specification defining <parameter>binaryformat</parameter>.</para>

	<para>OpenGL copies the shader binary data when
	<function>glShaderBinary</function> is called, so an application
	may free its copy of the data immediately after
	the function returns.</para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
	<para><constant>GL_INVALID_ENUM</constant> is generated if
	<parameter>binaryformat</parameter> is not a supported format returned in
	<constant>GL_SHADER_BINARY_FORMATS</constant>.</para>

	<para><constant>GL_INVALID_VALUE</constant> is generated if any value in
	<parameter>shaders</parameter> is not a vlue generated by OpenGL.</para>

	<para><constant>GL_INVALID_VALUE</constant> is generated if the format of the
        data pointed to by <parameter>binary</parameter> does not match 
        <parameter>binaryformat</parameter>.</para>

	<para><constant>GL_INVALID_VALUE</constant> is generated if <parameter>n</parameter>
        or <parameter>length</parameter> is negative.</para>

	<para><constant>GL_INVALID_OPERATION</constant> is generated if any value in
	<parameter>shaders</parameter> 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 <parameter>shaders</parameter>.</para>
    </refsect1>
    <refsect1 id="associatedgets"><title>Associated Gets</title>
	<para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
	with arguments <constant>GL_NUM_SHADER_BINARY_FORMATS</constant>
        and <constant>GL_SHADER_BINARY_FORMATS</constant></para>

	<para><citerefentry><refentrytitle>glIsShader</refentrytitle></citerefentry></para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
	<para><citerefentry><refentrytitle>glCreateShader</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>glDeleteShader</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry></para>
    </refsect1>
    <refsect1 id="copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 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.
            <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
        </para>
    </refsect1>
</refentry>
