upstream-doc/man4/glGetProgram.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="glGetProgram">
   5     <refmeta>
   6     <refentrytitle>glGetProgram</refentrytitle>
   7     <manvolnum>3G</manvolnum>
   8     </refmeta>
   9     <refnamediv>
  10     <refname>glGetProgramiv</refname>
  11     <refpurpose>Returns a parameter from a program object</refpurpose>
  12     </refnamediv>
  13     <refsynopsisdiv><title>C Specification</title>
  14     <funcsynopsis>
  15         <funcprototype>
  16         <funcdef>void <function>glGetProgramiv</function></funcdef>
  17         <paramdef>GLuint <parameter>program</parameter></paramdef>
  18         <paramdef>GLenum <parameter>pname</parameter></paramdef>
  19         <paramdef>GLint *<parameter>params</parameter></paramdef>
  20         </funcprototype>
  21     </funcsynopsis>
  22     </refsynopsisdiv>
  23     <refsect1 id="parameters"><title>Parameters</title>
  24     <variablelist>
  25         <varlistentry>
  26         <term><parameter>program</parameter></term>
  27         <listitem>
  28             <para>Specifies the program object to be
  29             queried.</para>
  30         </listitem>
  31         </varlistentry>
  32         <varlistentry>
  33         <term><parameter>pname</parameter></term>
  34         <listitem>
  35             <para>Specifies the object parameter. Accepted
  36             symbolic names are
  37             <constant>GL_DELETE_STATUS</constant>,
  38             <constant>GL_LINK_STATUS</constant>,
  39             <constant>GL_VALIDATE_STATUS</constant>,
  40             <constant>GL_INFO_LOG_LENGTH</constant>,
  41             <constant>GL_ATTACHED_SHADERS</constant>,
  42             <constant>GL_ACTIVE_ATOMIC_COUNTER_BUFFERS</constant>,
  43             <constant>GL_ACTIVE_ATTRIBUTES</constant>,
  44             <constant>GL_ACTIVE_ATTRIBUTE_MAX_LENGTH</constant>,
  45             <constant>GL_ACTIVE_UNIFORMS</constant>,
  46             <constant>GL_ACTIVE_UNIFORM_BLOCKS</constant>,
  47             <constant>GL_ACTIVE_UNIFORM_BLOCK_MAX_NAME_LENGTH</constant>,
  48             <constant>GL_ACTIVE_UNIFORM_MAX_LENGTH</constant>,
  49             <constant>GL_COMPUTE_WORK_GROUP_SIZE</constant>
  50             <constant>GL_PROGRAM_BINARY_LENGTH</constant>,
  51             <constant>GL_TRANSFORM_FEEDBACK_BUFFER_MODE</constant>,
  52             <constant>GL_TRANSFORM_FEEDBACK_VARYINGS</constant>,
  53             <constant>GL_TRANSFORM_FEEDBACK_VARYING_MAX_LENGTH</constant>,
  54             <constant>GL_GEOMETRY_VERTICES_OUT</constant>,
  55             <constant>GL_GEOMETRY_INPUT_TYPE</constant>, and
  56             <constant>GL_GEOMETRY_OUTPUT_TYPE</constant>.</para>
  57         </listitem>
  58         </varlistentry>
  59         <varlistentry>
  60         <term><parameter>params</parameter></term>
  61         <listitem>
  62             <para>Returns the requested object parameter.</para>
  63         </listitem>
  64         </varlistentry>
  65     </variablelist>
  66     </refsect1>
  67     <refsect1 id="description"><title>Description</title>
  68     <para><function>glGetProgram</function>
  69     returns in <parameter>params</parameter>
  70     the value of a parameter for a specific program object. The following parameters are defined:</para>
  71
  72     <variablelist>
  73         <varlistentry>
  74         <term><constant>GL_DELETE_STATUS</constant></term>
  75         <listitem>
  76             <para>
  77             </para>
  78             <para> <parameter>params</parameter> returns
  79             <constant>GL_TRUE</constant> if
  80             <parameter>program</parameter> is currently flagged
  81             for deletion, and <constant>GL_FALSE</constant>
  82             otherwise.</para>
  83         </listitem>
  84         </varlistentry>
  85
  86         <varlistentry>
  87         <term><constant>GL_LINK_STATUS</constant></term>
  88         <listitem>
  89             <para>
  90             </para>
  91             <para> <parameter>params</parameter> returns
  92             <constant>GL_TRUE</constant> if the last link
  93             operation on <parameter>program</parameter> was
  94             successful, and <constant>GL_FALSE</constant>
  95             otherwise.</para>
  96         </listitem>
  97         </varlistentry>
  98
  99         <varlistentry>
 100         <term><constant>GL_VALIDATE_STATUS</constant></term>
 101         <listitem>
 102             <para>
 103             </para>
 104             <para> <parameter>params</parameter> returns
 105             <constant>GL_TRUE</constant> or if the last
 106             validation operation on
 107             <parameter>program</parameter> was successful, and
 108             <constant>GL_FALSE</constant>
 109             otherwise.</para>
 110         </listitem>
 111         </varlistentry>
 112
 113         <varlistentry>
 114         <term><constant>GL_INFO_LOG_LENGTH</constant></term>
 115         <listitem>
 116             <para>
 117             </para>
 118             <para> <parameter>params</parameter> returns the
 119             number of characters in the information log for
 120             <parameter>program</parameter> including the null
 121             termination character (i.e., the size of the
 122             character buffer required to store the information
 123             log). If <parameter>program</parameter> has no
 124             information log, a value of 0 is
 125             returned.</para>
 126         </listitem>
 127         </varlistentry>
 128
 129         <varlistentry>
 130         <term><constant>GL_ATTACHED_SHADERS</constant></term>
 131         <listitem>
 132             <para>
 133             </para>
 134             <para> <parameter>params</parameter> returns the
 135             number of shader objects attached to
 136             <parameter>program</parameter>.</para>
 137         </listitem>
 138         </varlistentry>
 139
 140         <varlistentry>
 141         <term><constant>GL_ACTIVE_ATOMIC_COUNTER_BUFFERS</constant></term>
 142         <listitem>
 143             <para>
 144             </para>
 145             <para> <parameter>params</parameter> returns the
 146             number of active attribute atomic counter buffers used by
 147             <parameter>program</parameter>.</para>
 148         </listitem>
 149         </varlistentry>
 150
 151         <varlistentry>
 152         <term><constant>GL_ACTIVE_ATTRIBUTES</constant></term>
 153         <listitem>
 154             <para>
 155             </para>
 156             <para> <parameter>params</parameter> returns the
 157             number of active attribute variables for
 158             <parameter>program</parameter>.</para>
 159         </listitem>
 160         </varlistentry>
 161
 162         <varlistentry>
 163         <term><constant>GL_ACTIVE_ATTRIBUTE_MAX_LENGTH</constant></term>
 164         <listitem>
 165             <para>
 166             </para>
 167             <para> <parameter>params</parameter> returns the
 168             length of the longest active attribute name for
 169             <parameter>program</parameter>, including the null
 170             termination character (i.e., the size of the
 171             character buffer required to store the longest
 172             attribute name). If no active attributes exist, 0 is
 173             returned.</para>
 174         </listitem>
 175         </varlistentry>
 176
 177         <varlistentry>
 178         <term><constant>GL_ACTIVE_UNIFORMS</constant></term>
 179         <listitem>
 180             <para>
 181             </para>
 182             <para> <parameter>params</parameter> returns the
 183             number of active uniform variables for
 184             <parameter>program</parameter>.</para>
 185         </listitem>
 186         </varlistentry>
 187
 188         <varlistentry>
 189         <term><constant>GL_ACTIVE_UNIFORM_MAX_LENGTH</constant></term>
 190         <listitem>
 191             <para>
 192             </para>
 193             <para> <parameter>params</parameter> returns the
 194             length of the longest active uniform variable name
 195             for <parameter>program</parameter>, including the
 196             null termination character (i.e., the size of the
 197             character buffer required to store the longest
 198             uniform variable name). If no active uniform
 199             variables exist, 0 is returned.</para>
 200         </listitem>
 201         </varlistentry>
 202
 203         <varlistentry>
 204         <term><constant>GL_PROGRAM_BINARY_LENGTH</constant></term>
 205         <listitem>
 206             <para>
 207             </para>
 208             <para> <parameter>params</parameter> returns the
 209             length of the program binary, in bytes that will be returned by
 210             a call to <citerefentry><refentrytitle>glGetProgramBinary</refentrytitle></citerefentry>.
 211             When a progam's <constant>GL_LINK_STATUS</constant> is <constant>GL_FALSE</constant>,
 212             its program binary length is zero.
 213             </para>
 214         </listitem>
 215         </varlistentry>
 216
 217         <varlistentry>
 218         <term><constant>GL_COMPUTE_WORK_GROUP_SIZE</constant></term>
 219         <listitem>
 220             <para>
 221             </para>
 222             <para> <parameter>params</parameter> returns an
 223             array of three integers containing the local work group size of
 224             the compute program as specified by its input layout qualifier(s).
 225             <parameter>program</parameter> must be the name of a program object
 226             that has been previously linked successfully and contains a binary
 227             for the compute shader stage.
 228             </para>
 229         </listitem>
 230         </varlistentry>
 231
 232         <varlistentry>
 233         <term><constant>GL_TRANSFORM_FEEDBACK_BUFFER_MODE</constant></term>
 234         <listitem>
 235             <para>
 236             </para>
 237             <para> <parameter>params</parameter> returns a symbolic constant
 238             indicating the buffer mode used when transform feedback is active.
 239             This may be <constant>GL_SEPARATE_ATTRIBS</constant> or
 240             <constant>GL_INTERLEAVED_ATTRIBS</constant>.</para>
 241         </listitem>
 242         </varlistentry>
 243
 244         <varlistentry>
 245         <term><constant>GL_TRANSFORM_FEEDBACK_VARYINGS</constant></term>
 246         <listitem>
 247             <para>
 248             </para>
 249             <para> <parameter>params</parameter> returns the number of varying
 250             variables to capture in transform feedback mode for the program.</para>
 251         </listitem>
 252         </varlistentry>
 253
 254         <varlistentry>
 255         <term><constant>GL_TRANSFORM_FEEDBACK_VARYING_MAX_LENGTH</constant></term>
 256         <listitem>
 257             <para>
 258             </para>
 259             <para> <parameter>params</parameter> returns the length of the longest
 260             variable name to be used for transform feedback, including the null-terminator.</para>
 261         </listitem>
 262         </varlistentry>
 263
 264         <varlistentry>
 265         <term><constant>GL_GEOMETRY_VERTICES_OUT</constant></term>
 266         <listitem>
 267             <para>
 268             </para>
 269             <para> <parameter>params</parameter> returns the maximum number of vertices
 270             that the geometry shader in <parameter>program</parameter> will output.</para>
 271         </listitem>
 272         </varlistentry>
 273
 274         <varlistentry>
 275         <term><constant>GL_GEOMETRY_INPUT_TYPE</constant></term>
 276         <listitem>
 277             <para>
 278             </para>
 279             <para> <parameter>params</parameter> returns a symbolic constant indicating
 280             the primitive type accepted as input to the geometry shader contained in
 281             <parameter>program</parameter>.</para>
 282         </listitem>
 283         </varlistentry>
 284
 285         <varlistentry>
 286         <term><constant>GL_GEOMETRY_OUTPUT_TYPE</constant></term>
 287         <listitem>
 288             <para>
 289             </para>
 290             <para> <parameter>params</parameter> returns a symbolic constant indicating
 291             the primitive type that will be output by the geometry shader contained
 292             in <parameter>program</parameter>.</para>
 293         </listitem>
 294         </varlistentry>
 295     </variablelist>
 296     </refsect1>
 297     <refsect1 id="notes"><title>Notes</title>
 298     <para>
 299             <constant>GL_ACTIVE_UNIFORM_BLOCKS</constant> and
 300             <constant>GL_ACTIVE_UNIFORM_BLOCK_MAX_NAME_LENGTH</constant>
 301             are available only if the GL version 3.1 or greater.
 302         </para>
 303     <para>
 304         <constant>GL_GEOMETRY_VERTICES_OUT</constant>, <constant>GL_GEOMETRY_INPUT_TYPE</constant>
 305         and <constant>GL_GEOMETRY_OUTPUT_TYPE</constant> are accepted only if the GL
 306         version is 3.2 or greater.
 307     </para>
 308     <para>
 309         <constant>GL_COMPUTE_WORK_GROUP_SIZE</constant> is accepted only if the
 310         GL version is 4.3 or greater.
 311     </para>
 312
 313     <para>If an error is generated, no change is made to the
 314     contents of <parameter>params</parameter>.</para>
 315     </refsect1>
 316     <refsect1 id="errors"><title>Errors</title>
 317     <para><constant>GL_INVALID_VALUE</constant>
 318     is generated if <parameter>program</parameter>
 319     is not a value generated by OpenGL.</para>
 320
 321     <para><constant>GL_INVALID_OPERATION</constant>
 322     is generated if <parameter>program</parameter>
 323     does not refer to a program object.</para>
 324
 325     <para><constant>GL_INVALID_OPERATION</constant> is generated if
 326     <parameter>pname</parameter> is <constant>GL_GEOMETRY_VERTICES_OUT</constant>,
 327     <constant>GL_GEOMETRY_INPUT_TYPE</constant>, or <constant>GL_GEOMETRY_OUTPUT_TYPE</constant>,
 328     and <parameter>program</parameter> does not contain a geometry shader.</para>
 329
 330     <para><constant>GL_INVALID_ENUM</constant>
 331     is generated if <parameter>pname</parameter>
 332     is not an accepted value.</para>
 333
 334     <para><constant>GL_INVALID_OPERATION</constant> is generated if <parameter>pname</parameter>
 335     is <constant>GL_COMPUTE_WORK_GROUP_SIZE</constant> and <parameter>program</parameter>
 336     does not contain a binary for the compute shader stage.</para>
 337
 338     </refsect1>
 339     <refsect1 id="associatedgets"><title>Associated Gets</title>
 340     <para><citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>
 341     with argument <parameter>program</parameter></para>
 342
 343     <para><citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>
 344     with argument <parameter>program</parameter></para>
 345
 346     <para><citerefentry><refentrytitle>glGetAttachedShaders</refentrytitle></citerefentry>
 347     with argument <parameter>program</parameter></para>
 348
 349     <para><citerefentry><refentrytitle>glGetProgramInfoLog</refentrytitle></citerefentry>
 350     with argument <parameter>program</parameter></para>
 351
 352     <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry>
 353     <parameter></parameter></para>
 354     </refsect1>
 355     <refsect1 id="seealso"><title>See Also</title>
 356     <para><citerefentry><refentrytitle>glAttachShader</refentrytitle></citerefentry>,
 357     <citerefentry><refentrytitle>glCreateProgram</refentrytitle></citerefentry>,
 358     <citerefentry><refentrytitle>glDeleteProgram</refentrytitle></citerefentry>,
 359     <citerefentry><refentrytitle>glGetShader</refentrytitle></citerefentry>,
 360     <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
 361     <citerefentry><refentrytitle>glValidateProgram</refentrytitle></citerefentry></para>
 362     </refsect1>
 363     <refsect1 id="Copyright"><title>Copyright</title>
 364         <para>
 365             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 366             Copyright <trademark class="copyright"></trademark> 2010-2011 Khronos Group.
 367             This material may be distributed subject to the terms and conditions set forth in
 368             the Open Publication License, v 1.0, 8 June 1999.
 369             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 370         </para>
 371     </refsect1>
 372 </refentry>