upstream-man-pages/man4/xhtml/glBindImageTexture.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   3 <!-- saved from url=(0013)about:internet -->
   4 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><link rel="stylesheet" type="text/css" href="opengl-man.css" /><title>glBindImageTexture - OpenGL 4 Reference Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glBindImageTexture"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glBindImageTexture — bind a level of a texture to an image unit</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glBindImageTexture</b>(</code></td><td>GLuint  </td><td><var class="pdparam">unit</var>, </td></tr><tr><td> </td><td>GLuint  </td><td><var class="pdparam">texture</var>, </td></tr><tr><td> </td><td>GLint  </td><td><var class="pdparam">level</var>, </td></tr><tr><td> </td><td>GLboolean  </td><td><var class="pdparam">layered</var>, </td></tr><tr><td> </td><td>GLint  </td><td><var class="pdparam">layer</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">access</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">format</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>unit</code></em></span></dt><dd><p>
   5                     Specifies the index of the image unit to which to bind the texture
   6                 </p></dd><dt><span class="term"><em class="parameter"><code>texture</code></em></span></dt><dd><p>
   7                     Specifies the name of the texture to bind to the image unit.
   8                 </p></dd><dt><span class="term"><em class="parameter"><code>level</code></em></span></dt><dd><p>
   9                     Specifies the level of the texture that is to be bound.
  10                 </p></dd><dt><span class="term"><em class="parameter"><code>layered</code></em></span></dt><dd><p>
  11                     Specifies whether a layered texture binding is to be established.
  12                 </p></dd><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>
  13                     If <em class="parameter"><code>layered</code></em> is <code class="constant">GL_FALSE</code>, specifies the layer of <em class="parameter"><code>texture</code></em> to be bound to the image unit. Ignored otherwise.
  14                 </p></dd><dt><span class="term"><em class="parameter"><code>access</code></em></span></dt><dd><p>
  15                     Specifies a token indicating the type of access that will be performed on the image.
  16                 </p></dd><dt><span class="term"><em class="parameter"><code>format</code></em></span></dt><dd><p>
  17                     Specifies the format that the elements of the image will be treated as for the purposes of formatted stores.
  18                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  19             <code class="function">glBindImageTexture</code> binds a single level of a texture to an image unit for the purpose of
  20             reading and writing it from shaders. <em class="parameter"><code>unit</code></em> specifies the zero-based index of the image
  21             unit to which to bind the texture level. <em class="parameter"><code>texture</code></em> specifies the name of an existing texture
  22             object to bind to the image unit. If <em class="parameter"><code>texture</code></em> is zero, then any existing binding to
  23             the image unit is broken. <em class="parameter"><code>level</code></em> specifies the level of the texture to bind to the image
  24             unit.
  25         </p><p>
  26             If <em class="parameter"><code>texture</code></em> is the name of a one-, two-, or three-dimensional array texture, a cube map
  27             or cube map array texture, or a two-dimensional multisample array texture, then it is possible to bind either
  28             the entire array, or only a single layer of the array to the image unit. In such cases, if <em class="parameter"><code>layered</code></em>
  29             is <code class="constant">GL_TRUE</code>, the entire array is attached to the image unit and <em class="parameter"><code>layer</code></em>
  30             is ignored. However, if <em class="parameter"><code>layered</code></em> is <code class="constant">GL_FALSE</code> then <em class="parameter"><code>layer</code></em>
  31             specifies the layer of the array to attach to the image unit.
  32         </p><p>
  33             <em class="parameter"><code>access</code></em> specifies the access types to be performed by shaders and may be set to
  34             <code class="constant">GL_READ_ONLY</code>, <code class="constant">GL_WRITE_ONLY</code>, or <code class="constant">GL_READ_WRITE</code>
  35             to indicate read-only, write-only or read-write access, respectively. Violation of the access type specified in <em class="parameter"><code>access</code></em>
  36             (for example, if a shader writes to an image bound with <em class="parameter"><code>access</code></em> set to <code class="constant">GL_READ_ONLY</code>)
  37             will lead to undefined results, possibly including program termination.
  38         </p><p>
  39             <em class="parameter"><code>format</code></em> specifies the format that is to be used when performing formatted stores into the
  40             image from shaders. <em class="parameter"><code>format</code></em> must be compatible with the texture's internal format and must
  41             be one of the formats listed in the following table.
  42         </p><p>
  43             </p><div class="table"><a id="id4799703"></a><p class="title"><b>Table 1. Internal Image Formats</b></p><table summary="Internal Image Formats" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left"><span class="bold"><strong>
  44                         Image Unit Format
  45                         </strong></span></th><th align="left"><span class="bold"><strong>
  46                         Format Qualifier
  47                         </strong></span></th></tr></thead><tbody><tr><td align="left"><code class="constant">GL_RGBA32F</code></td><td align="left"><code class="code">rgba32f</code></td></tr><tr><td align="left"><code class="constant">GL_RGBA16F</code></td><td align="left"><code class="code">rgba16f</code></td></tr><tr><td align="left"><code class="constant">GL_RG32F</code></td><td align="left"><code class="code">rg32f</code></td></tr><tr><td align="left"><code class="constant">GL_RG16F</code></td><td align="left"><code class="code">rg16f</code></td></tr><tr><td align="left"><code class="constant">GL_R11F_G11F_B10F</code></td><td align="left"><code class="code">r11f_g11f_b10f</code></td></tr><tr><td align="left"><code class="constant">GL_R32F</code></td><td align="left"><code class="code">r32f</code></td></tr><tr><td align="left"><code class="constant">GL_R16F</code></td><td align="left"><code class="code">r16f</code></td></tr><tr><td align="left"><code class="constant">GL_RGBA32UI</code></td><td align="left"><code class="code">rgba32ui</code></td></tr><tr><td align="left"><code class="constant">GL_RGBA16UI</code></td><td align="left"><code class="code">rgba16ui</code></td></tr><tr><td align="left"><code class="constant">GL_RGB10_A2UI</code></td><td align="left"><code class="code">rgb10_a2ui</code></td></tr><tr><td align="left"><code class="constant">GL_RGBA8UI</code></td><td align="left"><code class="code">rgba8ui</code></td></tr><tr><td align="left"><code class="constant">GL_RG32UI</code></td><td align="left"><code class="code">rg32ui</code></td></tr><tr><td align="left"><code class="constant">GL_RG16UI</code></td><td align="left"><code class="code">rg16ui</code></td></tr><tr><td align="left"><code class="constant">GL_RG8UI</code></td><td align="left"><code class="code">rg8ui</code></td></tr><tr><td align="left"><code class="constant">GL_R32UI</code></td><td align="left"><code class="code">r32ui</code></td></tr><tr><td align="left"><code class="constant">GL_R16UI</code></td><td align="left"><code class="code">r16ui</code></td></tr><tr><td align="left"><code class="constant">GL_R8UI</code></td><td align="left"><code class="code">r8ui</code></td></tr><tr><td align="left"><code class="constant">GL_RGBA32I</code></td><td align="left"><code class="code">rgba32i</code></td></tr><tr><td align="left"><code class="constant">GL_RGBA16I</code></td><td align="left"><code class="code">rgba16i</code></td></tr><tr><td align="left"><code class="constant">GL_RGBA8I</code></td><td align="left"><code class="code">rgba8i</code></td></tr><tr><td align="left"><code class="constant">GL_RG32I</code></td><td align="left"><code class="code">rg32i</code></td></tr><tr><td align="left"><code class="constant">GL_RG16I</code></td><td align="left"><code class="code">rg16i</code></td></tr><tr><td align="left"><code class="constant">GL_RG8I</code></td><td align="left"><code class="code">rg8i</code></td></tr><tr><td align="left"><code class="constant">GL_R32I</code></td><td align="left"><code class="code">r32i</code></td></tr><tr><td align="left"><code class="constant">GL_R16I</code></td><td align="left"><code class="code">r16i</code></td></tr><tr><td align="left"><code class="constant">GL_R8I</code></td><td align="left"><code class="code">r8i</code></td></tr><tr><td align="left"><code class="constant">GL_RGBA16</code></td><td align="left"><code class="code">rgba16</code></td></tr><tr><td align="left"><code class="constant">GL_RGB10_A2</code></td><td align="left"><code class="code">rgb10_a2</code></td></tr><tr><td align="left"><code class="constant">GL_RGBA8</code></td><td align="left"><code class="code">rgba8</code></td></tr><tr><td align="left"><code class="constant">GL_RG16</code></td><td align="left"><code class="code">rg16</code></td></tr><tr><td align="left"><code class="constant">GL_RG8</code></td><td align="left"><code class="code">rg8</code></td></tr><tr><td align="left"><code class="constant">GL_R16</code></td><td align="left"><code class="code">r16</code></td></tr><tr><td align="left"><code class="constant">GL_R8</code></td><td align="left"><code class="code">r8</code></td></tr><tr><td align="left"><code class="constant">GL_RGBA16_SNORM</code></td><td align="left"><code class="code">rgba16_snorm</code></td></tr><tr><td align="left"><code class="constant">GL_RGBA8_SNORM</code></td><td align="left"><code class="code">rgba8_snorm</code></td></tr><tr><td align="left"><code class="constant">GL_RG16_SNORM</code></td><td align="left"><code class="code">rg16_snorm</code></td></tr><tr><td align="left"><code class="constant">GL_RG8_SNORM</code></td><td align="left"><code class="code">rg8_snorm</code></td></tr><tr><td align="left"><code class="constant">GL_R16_SNORM</code></td><td align="left"><code class="code">r16_snorm</code></td></tr><tr><td align="left"><code class="constant">GL_R8_SNORM</code></td><td align="left"><code class="code">r8_snorm</code></td></tr></tbody></table></div><p>
  48         </p><p>
  49             When a texture is bound to an image unit, the <em class="parameter"><code>format</code></em> parameter for the image
  50             unit need not exactly match the texture internal format as long as the formats are
  51             considered compatible as defined in the OpenGL Specification. The matching criterion used
  52             for a given texture may be determined by calling <a href="glGetTexParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexParameter</span></span></a>
  53             with <em class="parameter"><code>value</code></em>
  54             set to <code class="constant">GL_IMAGE_FORMAT_COMPATIBILITY_TYPE</code>, with return values of <code class="constant">GL_IMAGE_FORMAT_COMPATIBILITY_BY_SIZE</code>
  55             and <code class="constant">GL_IMAGE_FORMAT_COMPATIBILITY_BY_CLASS</code>, specifying matches by size and class, respectively.
  56         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
  57             The <code class="function">glBindImageTexture</code> is available only if the GL version is 4.2 or greater.
  58         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
  59             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>unit</code></em> greater than or equal to the
  60             value of <code class="constant">GL_MAX_IMAGE_UNITS</code>.
  61         </p><p>
  62             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>texture</code></em> is not the name of
  63             an existing texture object.
  64         </p><p>
  65             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>level</code></em> or <em class="parameter"><code>layer</code></em>
  66             is less than zero.
  67         </p><p>
  68             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>access</code></em> or <em class="parameter"><code>format</code></em>
  69             is not one of the supported tokens.
  70         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
  71             <a href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_IMAGE_BINDING_NAME</code>.
  72         </p><p>
  73             <a href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_IMAGE_BINDING_LEVEL</code>.
  74         </p><p>
  75             <a href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_IMAGE_BINDING_LAYERED</code>.
  76         </p><p>
  77             <a href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_IMAGE_BINDING_LAYER</code>.
  78         </p><p>
  79             <a href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_IMAGE_BINDING_ACCESS</code>.
  80         </p><p>
  81             <a href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_IMAGE_BINDING_FORMAT</code>.
  82         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
  83             <a href="glGenTextures.xml"><span class="citerefentry"><span class="refentrytitle">glGenTextures</span></span></a>,
  84             <a href="glTexImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage1D</span></span></a>,
  85             <a href="glTexImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage2D</span></span></a>,
  86             <a href="glTexImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage3D</span></span></a>,
  87             <a href="glTexStorage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexStorage1D</span></span></a>,
  88             <a href="glTexStorage2D.xml"><span class="citerefentry"><span class="refentrytitle">glTexStorage2D</span></span></a>,
  89             <a href="glTexStorage3D.xml"><span class="citerefentry"><span class="refentrytitle">glTexStorage3D</span></span></a>,
  90             <a href="glBindTexture.xml"><span class="citerefentry"><span class="refentrytitle">glBindTexture</span></span></a>
  91         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
  92             Copyright <span class="trademark"></span>© 2011 Khronos Group.
  93             This material may be distributed subject to the terms and conditions set forth in
  94             the Open Publication License, v 1.0, 8 June 1999.
  95             <a href="http://opencontent.org/openpub/" target="_top">http://opencontent.org/openpub/</a>.
  96         </p></div></div></body></html>