Commit | Line | Data |
---|---|---|
7faf1d71 AW |
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> |