upstream-man-pages/man4/glGetProgramInterface.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="glGetProgramInterface">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2012</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glGetProgramInterface</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glGetProgramInterface</refname>
  17         <refpurpose>query a property of an interface in a program</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glGetProgramInterfaceiv</function></funcdef>
  23                 <paramdef>GLuint <parameter>program</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>programInterface</parameter></paramdef>
  25                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  26                 <paramdef>GLint * <parameter>params</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                     The name of a program object whose interface to query.
  37                 </para>
  38             </listitem>
  39         </varlistentry>
  40         <varlistentry>
  41             <term><parameter>programInterface</parameter></term>
  42             <listitem>
  43                 <para>
  44                     A token identifying the interface within <parameter>program</parameter> to query.
  45                 </para>
  46             </listitem>
  47         </varlistentry>
  48         <varlistentry>
  49             <term><parameter>pname</parameter></term>
  50             <listitem>
  51                 <para>
  52                     The name of the parameter within <parameter>programInterface</parameter> to query.
  53                 </para>
  54             </listitem>
  55         </varlistentry>
  56         <varlistentry>
  57             <term><parameter>params</parameter></term>
  58             <listitem>
  59                 <para>
  60                     The address of a variable to retrieve the value of <parameter>pname</parameter> for the program interface.
  61                 </para>
  62             </listitem>
  63         </varlistentry>
  64         </variablelist>
  65     </refsect1>
  66     <refsect1 id="description"><title>Description</title>
  67         <para>
  68             <function>glGetProgramInterfaceiv</function> queries the property of the interface identifed
  69             by <parameter>programInterface</parameter> in <parameter>program</parameter>, the property name of
  70             which is given by <parameter>pname</parameter>.
  71         </para>
  72         <para>
  73             <parameter>program</parameter> must be the name of an existing program object. <parameter>programInterface</parameter>
  74             is the name of the interface within <parameter>program</parameter> to query and must be one of the following
  75             values:
  76         </para>
  77         <variablelist>
  78             <varlistentry>
  79                 <term><constant>GL_UNIFORM</constant></term>
  80                 <listitem>
  81                     <para>
  82                         The query is targeted at the set of active uniforms within <parameter>program</parameter>.
  83                     </para>
  84                 </listitem>
  85             </varlistentry>
  86             <varlistentry>
  87                 <term><constant>GL_UNIFORM_BLOCK</constant></term>
  88                 <listitem>
  89                     <para>
  90                         The query is targeted at the set of active uniform blocks within <parameter>program</parameter>.
  91                     </para>
  92                 </listitem>
  93             </varlistentry>
  94             <varlistentry>
  95                 <term><constant>GL_ATOMIC_COUNTER_BUFFER</constant></term>
  96                 <listitem>
  97                     <para>
  98                         The query is targeted at the set of active atomic counter buffer binding points within <parameter>program</parameter>.
  99                     </para>
 100                 </listitem>
 101             </varlistentry>
 102             <varlistentry>
 103                 <term><constant>GL_PROGRAM_INPUT</constant></term>
 104                 <listitem>
 105                     <para>
 106                         The query is targeted at the set of active input variables used by the first shader stage of <parameter>program</parameter>.
 107                         If <parameter>program</parameter> contains multiple shader stages then input variables from any stage other than the first
 108                         will not be enumerated.
 109                     </para>
 110                 </listitem>
 111             </varlistentry>
 112             <varlistentry>
 113                 <term><constant>GL_PROGRAM_OUTPUT</constant></term>
 114                 <listitem>
 115                     <para>
 116                         The query is targeted at the set of active output variables produced by the last shader stage of <parameter>program</parameter>.
 117                         If <parameter>program</parameter> contains multiple shader stages then output variables from any stage other than the last
 118                         will not be enumerated.
 119                     </para>
 120                 </listitem>
 121             </varlistentry>
 122             <varlistentry>
 123                 <term><constant>GL_VERTEX_SUBROUTINE</constant></term>,
 124                 <term><constant>GL_TESS_CONTROL_SUBROUTINE</constant></term>,
 125                 <term><constant>GL_TESS_EVALUATION_SUBROUTINE</constant></term>,
 126                 <term><constant>GL_GEOMETRY_SUBROUTINE</constant></term>,
 127                 <term><constant>GL_FRAGMENT_SUBROUTINE</constant></term>,
 128                 <term><constant>GL_COMPUTE_SUBROUTINE</constant></term>
 129                 <listitem>
 130                     <para>
 131                         The query is targeted at the set of active subroutines for the vertex, tessellation control, tessellation evaluation,
 132                         geometry, fragment and compute shader stages of <parameter>program</parameter>, respectively.
 133                     </para>
 134                 </listitem>
 135             </varlistentry>
 136             <varlistentry>
 137                 <term><constant>GL_VERTEX_SUBROUTINE_UNIFORM</constant></term>,
 138                 <term><constant>GL_TESS_CONTROL_SUBROUTINE_UNIFORM</constant></term>,
 139                 <term><constant>GL_TESS_EVALUATION_SUBROUTINE_UNIFORM</constant></term>,
 140                 <term><constant>GL_GEOMETRY_SUBROUTINE_UNIFORM</constant></term>,
 141                 <term><constant>GL_FRAGMENT_SUBROUTINE_UNIFORM</constant></term>,
 142                 <term><constant>GL_COMPUTE_SUBROUTINE_UNIFORM</constant></term>
 143                 <listitem>
 144                     <para>
 145                         The query is targeted at the set of active subroutine uniform variables used by the vertex, tessellation control, tessellation evaluation,
 146                         geometry, fragment and compute shader stages of <parameter>program</parameter>, respectively.
 147                     </para>
 148                 </listitem>
 149             </varlistentry>
 150             <varlistentry>
 151                 <term><constant>GL_TRANSFORM_FEEDBACK_VARYING</constant></term>
 152                 <listitem>
 153                     <para>
 154                         The query is targeted at the set of output variables from the last non-fragment stage of <parameter>program</parameter> that would be
 155                         captured if transform feedback were active.
 156                     </para>
 157                 </listitem>
 158             </varlistentry>
 159             <varlistentry>
 160                 <term><constant>GL_BUFFER_VARIABLE</constant></term>
 161                 <listitem>
 162                     <para>
 163                         The query is targeted at the set of active buffer variables used by <parameter>program</parameter>.
 164                     </para>
 165                 </listitem>
 166             </varlistentry>
 167             <varlistentry>
 168                 <term><constant>GL_SHADER_STORAGE_BLOCK</constant></term>
 169                 <listitem>
 170                     <para>
 171                         The query is targeted at the set of active shader storage blocks used by <parameter>program</parameter>.
 172                     </para>
 173                 </listitem>
 174             </varlistentry>
 175         </variablelist>
 176         <para>
 177             <parameter>pname</parameter> identifies the property of <parameter>programInterface</parameter>
 178             to return in <parameter>params</parameter>.
 179         </para>
 180         <para>
 181             If <parameter>pname</parameter> is <constant>GL_ACTIVE_RESOURCES</constant>, the value returned is the number of
 182             resources in the active resource list for <parameter>programInterface</parameter>.  If the list
 183             of active resources for <parameter>programInterface</parameter> is empty, zero is returned.
 184         </para>
 185         <para>
 186             If <parameter>pname</parameter> is <constant>GL_MAX_NAME_LENGTH</constant>, the value returned is the length of the
 187             longest active name string for an active resource in <parameter>programInterface</parameter>.
 188             This length includes an extra character for the null terminator.  If the
 189             list of active resources for <parameter>programInterface</parameter> is empty, zero is
 190             returned.  It is an error to specify <constant>GL_MAX_NAME_LENGTH</constant> when <parameter>programInterface</parameter>
 191             is <constant>GL_ATOMIC_COUNTER_BUFFER</constant>, as active atomic counter buffer resources are
 192             not assigned name strings.
 193         </para>
 194         <para>
 195             If <parameter>pname</parameter> is <constant>GL_MAX_NUM_ACTIVE_VARIABLES</constant>, the value returned is the number
 196             of active variables belonging to the interface block or atomic counter
 197             buffer resource in <parameter>programInterface</parameter> with the most active variables.  If
 198             the list of active resources for <parameter>programInterface</parameter> is empty, zero is
 199             returned.  When <parameter>pname</parameter> is <constant>GL_MAX_NUM_ACTIVE_VARIABLES</constant>, <parameter>programInterface</parameter>
 200             must be <constant>GL_UNIFORM_BLOCK</constant>, <constant>GL_ATOMIC_COUNTER_BUFFER</constant>, or <constant>GL_SHADER_STORAGE_BLOCK</constant>.
 201         </para>
 202         <para>
 203             If <parameter>pname</parameter> is <constant>GL_MAX_NUM_COMPATIBLE_SUBROUTINES</constant>, the value returned is the
 204             number of compatible subroutines belonging to the active subroutine
 205             uniform in <parameter>programInterface</parameter> with the most compatible subroutines.  If
 206             the list of active resources for <parameter>programInterface</parameter> is empty, zero is
 207             returned. When <parameter>pname</parameter> is <constant>GL_MAX_NUM_COMPATIBLE_SUBROUTINES</constant>,
 208             <parameter>programInterface</parameter> must be one of <constant>GL_VERTEX_SUBROUTINE_UNIFORM</constant>,
 209             <constant>GL_TESS_CONTROL_SUBROUTINE_UNIFORM</constant>, <constant>GL_TESS_EVALUATION_SUBROUTINE_UNIFORM</constant>,
 210             <constant>GL_GEOMETRY_SUBROUTINE_UNIFORM</constant>, <constant>GL_FRAGMENT_SUBROUTINE_UNIFORM</constant>, or
 211             <constant>GL_COMPUTE_SUBROUTINE_UNIFORM</constant>.
 212         </para>
 213     </refsect1>
 214     <refsect1 id="errors"><title>Errors</title>
 215         <para>
 216             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>identifier</parameter>
 217             is not one of the accepted object types.
 218         </para>
 219         <para>
 220             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>program</parameter>
 221             is not the name of an existing sync object.
 222         </para>
 223         <para>
 224             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>bufSize</parameter> is
 225             zero.
 226         </para>
 227         <para>
 228             If not NULL, <parameter>length</parameter> and <parameter>label</parameter> should be addresses
 229             to which the client has write access, otherwise undefined behavior, including process termination
 230             may occur.
 231         </para>
 232     </refsect1>
 233     <refsect1 id="associatedgets"><title>Associated Gets</title>
 234         <para>
 235             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_LABEL_LENGTH</constant>.
 236         </para>
 237     </refsect1>
 238     <refsect1 id="seealso"><title>See Also</title>
 239         <para>
 240             <citerefentry><refentrytitle>glPushDebugGroup</refentrytitle></citerefentry>,
 241             <citerefentry><refentrytitle>glPopDebugGroup</refentrytitle></citerefentry>,
 242             <citerefentry><refentrytitle>glObjectLabel</refentrytitle></citerefentry>,
 243             <citerefentry><refentrytitle>glGetObjectLabel</refentrytitle></citerefentry>.
 244         </para>
 245     </refsect1>
 246     <refsect1 id="Copyright"><title>Copyright</title>
 247         <para>
 248             Copyright <trademark class="copyright"></trademark> 2012 Khronos Group.
 249             This material may be distributed subject to the terms and conditions set forth in
 250             the Open Publication License, v 1.0, 8 June 1999.
 251             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 252         </para>
 253     </refsect1>
 254 </refentry>