upstream-man-pages/man4/glProgramBinary.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
   3               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
   4 <refentry id="glProgramBinary">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2010</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glProgramBinary</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glProgramBinary</refname>
  17         <refpurpose>load a program object with a program binary</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glProgramBinary</function></funcdef>
  23                 <paramdef>GLuint <parameter>program</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>binaryFormat</parameter></paramdef>
  25                 <paramdef>const void *<parameter>binary</parameter></paramdef>
  26                 <paramdef>GLsizei <parameter>length</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29     </refsynopsisdiv>
  30     <refsect1 id="parameters"><title>Parameters</title>
  31         <variablelist>
  32         <varlistentry>
  33             <term><parameter>program</parameter></term>
  34             <listitem>
  35             <para>
  36                 Specifies the name of a program object into which to load a program binary.
  37             </para>
  38             </listitem>
  39         </varlistentry>
  40         <varlistentry>
  41             <term><parameter>binaryFormat</parameter></term>
  42             <listitem>
  43             <para>
  44                 Specifies the format of the binary data in binary.
  45             </para>
  46             </listitem>
  47         </varlistentry>
  48         <varlistentry>
  49             <term><parameter>binary</parameter></term>
  50             <listitem>
  51             <para>
  52                 Specifies the address an array containing the binary to be loaded into <parameter>program</parameter>.
  53             </para>
  54             </listitem>
  55         </varlistentry>
  56         <varlistentry>
  57             <term><parameter>length</parameter></term>
  58             <listitem>
  59             <para>
  60                 Specifies the number of bytes contained in <parameter>binary</parameter>.
  61             </para>
  62             </listitem>
  63         </varlistentry>
  64         </variablelist>
  65     </refsect1>
  66     <refsect1 id="description"><title>Description</title>
  67         <para>
  68             <function>glProgramBinary</function> loads a program object with a program binary previously
  69             returned from <citerefentry><refentrytitle>glGetProgramBinary</refentrytitle></citerefentry>.
  70             <parameter>binaryFormat</parameter> and <parameter>binary</parameter> must be those returned
  71             by a previous call to <citerefentry><refentrytitle>glGetProgramBinary</refentrytitle></citerefentry>,
  72             and <parameter>length</parameter> must be the length returned by
  73             <citerefentry><refentrytitle>glGetProgramBinary</refentrytitle></citerefentry>, or by
  74             <citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry> when called with
  75             <parameter>pname</parameter> set to <constant>GL_PROGRAM_BINARY_LENGTH</constant>.
  76             If these conditions are not met, loading the program binary will fail and <parameter>program</parameter>'s
  77             <constant>GL_LINK_STATUS</constant> will be set to <constant>GL_FALSE</constant>.
  78         </para>
  79         <para>
  80             A program object's program binary is replaced by calls to
  81             <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry> or
  82             <function>glProgramBinary</function>. When linking success or failure is concerned, <function>glProgramBinary</function>
  83             can be considered to perform an implicit linking operation.
  84             <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry> and <function>glProgramBinary</function>
  85             both set the program object's <constant>GL_LINK_STATUS</constant> to <constant>GL_TRUE</constant>
  86             or <constant>GL_FALSE</constant>.
  87         </para>
  88         <para>
  89             A successful call to <function>glProgramBinary</function> will reset all uniform variables to their
  90             initial values. The initial value is either the value of the variable's initializer as specified in the
  91             original shader source, or zero if no initializer was present. Additionally, all vertex shader input
  92             and fragment shader output assignments that were in effect when the program was linked before saving are
  93             restored with <function>glProgramBinary</function> is called.
  94         </para>
  95     </refsect1>
  96     <refsect1 id="errors"><title>Errors</title>
  97         <para>
  98             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>program</parameter> is not the
  99             name of an existing program object.
 100         </para>
 101         <para>
 102             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>binaryFormat</parameter> is not a
 103             value recognized by the implementation.
 104         </para>
 105     </refsect1>
 106     <refsect1 id="notes"><title>Notes</title>
 107         <para>
 108             A program binary may fail to load if the implementation determines that there has been a
 109             change in hardware or software configuration from when the program binary was produced such
 110             as having been compiled with an incompatible or outdated version of the compiler.
 111         </para>
 112     </refsect1>
 113     <refsect1 id="associatedgets"><title>Associated Gets</title>
 114         <para>
 115             <citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry> with argument <constant>GL_PROGRAM_BINARY_LENGTH</constant>
 116         </para>
 117         <para>
 118             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_NUM_PROGRAM_BINARY_FORMATS</constant>
 119         </para>
 120         <para>
 121             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PROGRAM_BINARY_FORMATS</constant>
 122         </para>
 123     </refsect1>
 124     <refsect1 id="seealso"><title>See Also</title>
 125         <para>
 126             <citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>,
 127             <citerefentry><refentrytitle>glGetProgramBinary</refentrytitle></citerefentry>
 128         </para>
 129     </refsect1>
 130     <refsect1 id="Copyright"><title>Copyright</title>
 131         <para>
 132             Copyright <trademark class="copyright"></trademark> 2010 Khronos Group.
 133             This material may be distributed subject to the terms and conditions set forth in
 134             the Open Publication License, v 1.0, 8 June 1999.
 135             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 136         </para>
 137     </refsect1>
 138 </refentry>