| 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="glBindImageTexture"> |
| 5 | <refmeta> |
| 6 | <refmetainfo> |
| 7 | <copyright> |
| 8 | <year>2010</year> |
| 9 | <holder>Khronos Group</holder>> |
| 10 | </copyright> |
| 11 | </refmetainfo> |
| 12 | <refentrytitle>glBindImageTexture</refentrytitle> |
| 13 | <manvolnum>3G</manvolnum> |
| 14 | </refmeta> |
| 15 | <refnamediv> |
| 16 | <refname>glBindImageTexture</refname> |
| 17 | <refpurpose>bind a level of a texture to an image unit</refpurpose> |
| 18 | </refnamediv> |
| 19 | <refsynopsisdiv><title>C Specification</title> |
| 20 | <funcsynopsis> |
| 21 | <funcprototype> |
| 22 | <funcdef>void <function>glBindImageTexture</function></funcdef> |
| 23 | <paramdef>GLuint <parameter>unit</parameter></paramdef> |
| 24 | <paramdef>GLuint <parameter>texture</parameter></paramdef> |
| 25 | <paramdef>GLint <parameter>level</parameter></paramdef> |
| 26 | <paramdef>GLboolean <parameter>layered</parameter></paramdef> |
| 27 | <paramdef>GLint <parameter>layer</parameter></paramdef> |
| 28 | <paramdef>GLenum <parameter>access</parameter></paramdef> |
| 29 | <paramdef>GLenum <parameter>format</parameter></paramdef> |
| 30 | </funcprototype> |
| 31 | </funcsynopsis> |
| 32 | </refsynopsisdiv> |
| 33 | <refsect1 id="parameters"><title>Parameters</title> |
| 34 | <variablelist> |
| 35 | <varlistentry> |
| 36 | <term><parameter>unit</parameter></term> |
| 37 | <listitem> |
| 38 | <para> |
| 39 | Specifies the index of the image unit to which to bind the texture |
| 40 | </para> |
| 41 | </listitem> |
| 42 | </varlistentry> |
| 43 | <varlistentry> |
| 44 | <term><parameter>texture</parameter></term> |
| 45 | <listitem> |
| 46 | <para> |
| 47 | Specifies the name of the texture to bind to the image unit. |
| 48 | </para> |
| 49 | </listitem> |
| 50 | </varlistentry> |
| 51 | <varlistentry> |
| 52 | <term><parameter>level</parameter></term> |
| 53 | <listitem> |
| 54 | <para> |
| 55 | Specifies the level of the texture that is to be bound. |
| 56 | </para> |
| 57 | </listitem> |
| 58 | </varlistentry> |
| 59 | <varlistentry> |
| 60 | <term><parameter>layered</parameter></term> |
| 61 | <listitem> |
| 62 | <para> |
| 63 | Specifies whether a layered texture binding is to be established. |
| 64 | </para> |
| 65 | </listitem> |
| 66 | </varlistentry> |
| 67 | <varlistentry> |
| 68 | <term><parameter>layer</parameter></term> |
| 69 | <listitem> |
| 70 | <para> |
| 71 | If <parameter>layered</parameter> is <constant>GL_FALSE</constant>, specifies the layer of <parameter>texture</parameter> to be bound to the image unit. Ignored otherwise. |
| 72 | </para> |
| 73 | </listitem> |
| 74 | </varlistentry> |
| 75 | <varlistentry> |
| 76 | <term><parameter>access</parameter></term> |
| 77 | <listitem> |
| 78 | <para> |
| 79 | Specifies a token indicating the type of access that will be performed on the image. |
| 80 | </para> |
| 81 | </listitem> |
| 82 | </varlistentry> |
| 83 | <varlistentry> |
| 84 | <term><parameter>format</parameter></term> |
| 85 | <listitem> |
| 86 | <para> |
| 87 | Specifies the format that the elements of the image will be treated as for the purposes of formatted stores. |
| 88 | </para> |
| 89 | </listitem> |
| 90 | </varlistentry> |
| 91 | </variablelist> |
| 92 | </refsect1> |
| 93 | <refsect1 id="description"><title>Description</title> |
| 94 | <para> |
| 95 | <function>glBindImageTexture</function> binds a single level of a texture to an image unit for the purpose of |
| 96 | reading and writing it from shaders. <parameter>unit</parameter> specifies the zero-based index of the image |
| 97 | unit to which to bind the texture level. <parameter>texture</parameter> specifies the name of an existing texture |
| 98 | object to bind to the image unit. If <parameter>texture</parameter> is zero, then any existing binding to |
| 99 | the image unit is broken. <parameter>level</parameter> specifies the level of the texture to bind to the image |
| 100 | unit. |
| 101 | </para> |
| 102 | <para> |
| 103 | If <parameter>texture</parameter> is the name of a one-, two-, or three-dimensional array texture, a cube map |
| 104 | or cube map array texture, or a two-dimensional multisample array texture, then it is possible to bind either |
| 105 | the entire array, or only a single layer of the array to the image unit. In such cases, if <parameter>layered</parameter> |
| 106 | is <constant>GL_TRUE</constant>, the entire array is attached to the image unit and <parameter>layer</parameter> |
| 107 | is ignored. However, if <parameter>layered</parameter> is <constant>GL_FALSE</constant> then <parameter>layer</parameter> |
| 108 | specifies the layer of the array to attach to the image unit. |
| 109 | </para> |
| 110 | <para> |
| 111 | <parameter>access</parameter> specifies the access types to be performed by shaders and may be set to |
| 112 | <constant>GL_READ_ONLY</constant>, <constant>GL_WRITE_ONLY</constant>, or <constant>GL_READ_WRITE</constant> |
| 113 | to indicate read-only, write-only or read-write access, respectively. Violation of the access type specified in <parameter>access</parameter> |
| 114 | (for example, if a shader writes to an image bound with <parameter>access</parameter> set to <constant>GL_READ_ONLY</constant>) |
| 115 | will lead to undefined results, possibly including program termination. |
| 116 | </para> |
| 117 | <para> |
| 118 | <parameter>format</parameter> specifies the format that is to be used when performing formatted stores into the |
| 119 | image from shaders. <parameter>format</parameter> must be compatible with the texture's internal format and must |
| 120 | be one of the formats listed in the following table. |
| 121 | </para> |
| 122 | <para> |
| 123 | <table frame="topbot"><title>Internal Image Formats</title> |
| 124 | <tgroup cols="2" align="left"> |
| 125 | <colspec align="left"/> |
| 126 | <colspec align="left"/> |
| 127 | <thead> |
| 128 | <row> |
| 129 | <entry rowsep="1" align="left"><emphasis role="bold"> |
| 130 | Image Unit Format |
| 131 | </emphasis></entry> |
| 132 | <entry rowsep="1" align="left"><emphasis role="bold"> |
| 133 | Format Qualifier |
| 134 | </emphasis></entry> |
| 135 | </row> |
| 136 | </thead> |
| 137 | <tbody> |
| 138 | <row> |
| 139 | <entry><constant>GL_RGBA32F</constant></entry><entry><code>rgba32f</code></entry> |
| 140 | </row> |
| 141 | <row> |
| 142 | <entry><constant>GL_RGBA16F</constant></entry><entry><code>rgba16f</code></entry> |
| 143 | </row> |
| 144 | <row> |
| 145 | <entry><constant>GL_RG32F</constant></entry><entry><code>rg32f</code></entry> |
| 146 | </row> |
| 147 | <row> |
| 148 | <entry><constant>GL_RG16F</constant></entry><entry><code>rg16f</code></entry> |
| 149 | </row> |
| 150 | <row> |
| 151 | <entry><constant>GL_R11F_G11F_B10F</constant></entry><entry><code>r11f_g11f_b10f</code></entry> |
| 152 | </row> |
| 153 | <row> |
| 154 | <entry><constant>GL_R32F</constant></entry><entry><code>r32f</code></entry> |
| 155 | </row> |
| 156 | <row> |
| 157 | <entry><constant>GL_R16F</constant></entry><entry><code>r16f</code></entry> |
| 158 | </row> |
| 159 | <row> |
| 160 | <entry><constant>GL_RGBA32UI</constant></entry><entry><code>rgba32ui</code></entry> |
| 161 | </row> |
| 162 | <row> |
| 163 | <entry><constant>GL_RGBA16UI</constant></entry><entry><code>rgba16ui</code></entry> |
| 164 | </row> |
| 165 | <row> |
| 166 | <entry><constant>GL_RGB10_A2UI</constant></entry><entry><code>rgb10_a2ui</code></entry> |
| 167 | </row> |
| 168 | <row> |
| 169 | <entry><constant>GL_RGBA8UI</constant></entry><entry><code>rgba8ui</code></entry> |
| 170 | </row> |
| 171 | <row> |
| 172 | <entry><constant>GL_RG32UI</constant></entry><entry><code>rg32ui</code></entry> |
| 173 | </row> |
| 174 | <row> |
| 175 | <entry><constant>GL_RG16UI</constant></entry><entry><code>rg16ui</code></entry> |
| 176 | </row> |
| 177 | <row> |
| 178 | <entry><constant>GL_RG8UI</constant></entry><entry><code>rg8ui</code></entry> |
| 179 | </row> |
| 180 | <row> |
| 181 | <entry><constant>GL_R32UI</constant></entry><entry><code>r32ui</code></entry> |
| 182 | </row> |
| 183 | <row> |
| 184 | <entry><constant>GL_R16UI</constant></entry><entry><code>r16ui</code></entry> |
| 185 | </row> |
| 186 | <row> |
| 187 | <entry><constant>GL_R8UI</constant></entry><entry><code>r8ui</code></entry> |
| 188 | </row> |
| 189 | <row> |
| 190 | <entry><constant>GL_RGBA32I</constant></entry><entry><code>rgba32i</code></entry> |
| 191 | </row> |
| 192 | <row> |
| 193 | <entry><constant>GL_RGBA16I</constant></entry><entry><code>rgba16i</code></entry> |
| 194 | </row> |
| 195 | <row> |
| 196 | <entry><constant>GL_RGBA8I</constant></entry><entry><code>rgba8i</code></entry> |
| 197 | </row> |
| 198 | <row> |
| 199 | <entry><constant>GL_RG32I</constant></entry><entry><code>rg32i</code></entry> |
| 200 | </row> |
| 201 | <row> |
| 202 | <entry><constant>GL_RG16I</constant></entry><entry><code>rg16i</code></entry> |
| 203 | </row> |
| 204 | <row> |
| 205 | <entry><constant>GL_RG8I</constant></entry><entry><code>rg8i</code></entry> |
| 206 | </row> |
| 207 | <row> |
| 208 | <entry><constant>GL_R32I</constant></entry><entry><code>r32i</code></entry> |
| 209 | </row> |
| 210 | <row> |
| 211 | <entry><constant>GL_R16I</constant></entry><entry><code>r16i</code></entry> |
| 212 | </row> |
| 213 | <row> |
| 214 | <entry><constant>GL_R8I</constant></entry><entry><code>r8i</code></entry> |
| 215 | </row> |
| 216 | <row> |
| 217 | <entry><constant>GL_RGBA16</constant></entry><entry><code>rgba16</code></entry> |
| 218 | </row> |
| 219 | <row> |
| 220 | <entry><constant>GL_RGB10_A2</constant></entry><entry><code>rgb10_a2</code></entry> |
| 221 | </row> |
| 222 | <row> |
| 223 | <entry><constant>GL_RGBA8</constant></entry><entry><code>rgba8</code></entry> |
| 224 | </row> |
| 225 | <row> |
| 226 | <entry><constant>GL_RG16</constant></entry><entry><code>rg16</code></entry> |
| 227 | </row> |
| 228 | <row> |
| 229 | <entry><constant>GL_RG8</constant></entry><entry><code>rg8</code></entry> |
| 230 | </row> |
| 231 | <row> |
| 232 | <entry><constant>GL_R16</constant></entry><entry><code>r16</code></entry> |
| 233 | </row> |
| 234 | <row> |
| 235 | <entry><constant>GL_R8</constant></entry><entry><code>r8</code></entry> |
| 236 | </row> |
| 237 | <row> |
| 238 | <entry><constant>GL_RGBA16_SNORM</constant></entry><entry><code>rgba16_snorm</code></entry> |
| 239 | </row> |
| 240 | <row> |
| 241 | <entry><constant>GL_RGBA8_SNORM</constant></entry><entry><code>rgba8_snorm</code></entry> |
| 242 | </row> |
| 243 | <row> |
| 244 | <entry><constant>GL_RG16_SNORM</constant></entry><entry><code>rg16_snorm</code></entry> |
| 245 | </row> |
| 246 | <row> |
| 247 | <entry><constant>GL_RG8_SNORM</constant></entry><entry><code>rg8_snorm</code></entry> |
| 248 | </row> |
| 249 | <row> |
| 250 | <entry><constant>GL_R16_SNORM</constant></entry><entry><code>r16_snorm</code></entry> |
| 251 | </row> |
| 252 | <row> |
| 253 | <entry><constant>GL_R8_SNORM</constant></entry><entry><code>r8_snorm</code></entry> |
| 254 | </row> |
| 255 | </tbody> |
| 256 | </tgroup> |
| 257 | </table> |
| 258 | </para> |
| 259 | <para> |
| 260 | When a texture is bound to an image unit, the <parameter>format</parameter> parameter for the image |
| 261 | unit need not exactly match the texture internal format as long as the formats are |
| 262 | considered compatible as defined in the OpenGL Specification. The matching criterion used |
| 263 | for a given texture may be determined by calling <citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry> |
| 264 | with <parameter>value</parameter> |
| 265 | set to <constant>GL_IMAGE_FORMAT_COMPATIBILITY_TYPE</constant>, with return values of <constant>GL_IMAGE_FORMAT_COMPATIBILITY_BY_SIZE</constant> |
| 266 | and <constant>GL_IMAGE_FORMAT_COMPATIBILITY_BY_CLASS</constant>, specifying matches by size and class, respectively. |
| 267 | </para> |
| 268 | </refsect1> |
| 269 | <refsect1 id="notes"><title>Notes</title> |
| 270 | <para> |
| 271 | The <function>glBindImageTexture</function> is available only if the GL version is 4.2 or greater. |
| 272 | </para> |
| 273 | </refsect1> |
| 274 | <refsect1 id="errors"><title>Errors</title> |
| 275 | <para> |
| 276 | <constant>GL_INVALID_VALUE</constant> is generated if <parameter>unit</parameter> greater than or equal to the |
| 277 | value of <constant>GL_MAX_IMAGE_UNITS</constant>. |
| 278 | </para> |
| 279 | <para> |
| 280 | <constant>GL_INVALID_VALUE</constant> is generated if <parameter>texture</parameter> is not the name of |
| 281 | an existing texture object. |
| 282 | </para> |
| 283 | <para> |
| 284 | <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> or <parameter>layer</parameter> |
| 285 | is less than zero. |
| 286 | </para> |
| 287 | <para> |
| 288 | <constant>GL_INVALID_ENUM</constant> is generated if <parameter>access</parameter> or <parameter>format</parameter> |
| 289 | is not one of the supported tokens. |
| 290 | </para> |
| 291 | </refsect1> |
| 292 | <refsect1 id="associatedgets"><title>Associated Gets</title> |
| 293 | <para> |
| 294 | <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_IMAGE_BINDING_NAME</constant>. |
| 295 | </para> |
| 296 | <para> |
| 297 | <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_IMAGE_BINDING_LEVEL</constant>. |
| 298 | </para> |
| 299 | <para> |
| 300 | <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_IMAGE_BINDING_LAYERED</constant>. |
| 301 | </para> |
| 302 | <para> |
| 303 | <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_IMAGE_BINDING_LAYER</constant>. |
| 304 | </para> |
| 305 | <para> |
| 306 | <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_IMAGE_BINDING_ACCESS</constant>. |
| 307 | </para> |
| 308 | <para> |
| 309 | <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_IMAGE_BINDING_FORMAT</constant>. |
| 310 | </para> |
| 311 | </refsect1> |
| 312 | <refsect1 id="seealso"><title>See Also</title> |
| 313 | <para> |
| 314 | <citerefentry><refentrytitle>glGenTextures</refentrytitle></citerefentry>, |
| 315 | <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>, |
| 316 | <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>, |
| 317 | <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>, |
| 318 | <citerefentry><refentrytitle>glTexStorage1D</refentrytitle></citerefentry>, |
| 319 | <citerefentry><refentrytitle>glTexStorage2D</refentrytitle></citerefentry>, |
| 320 | <citerefentry><refentrytitle>glTexStorage3D</refentrytitle></citerefentry>, |
| 321 | <citerefentry><refentrytitle>glBindTexture</refentrytitle></citerefentry> |
| 322 | </para> |
| 323 | </refsect1> |
| 324 | <refsect1 id="Copyright"><title>Copyright</title> |
| 325 | <para> |
| 326 | Copyright <trademark class="copyright"></trademark> 2011 Khronos Group. |
| 327 | This material may be distributed subject to the terms and conditions set forth in |
| 328 | the Open Publication License, v 1.0, 8 June 1999. |
| 329 | <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>. |
| 330 | </para> |
| 331 | </refsect1> |
| 332 | </refentry> |