Name
OES_texture_buffer
Name Strings
GL_OES_texture_buffer
Contact
Jon Leech (oddhack 'at' sonic.net)
Daniel Koch, NVIDIA (dkoch 'at' nvidia.com)
Contributors
Pat Brown, NVIDIA
James Helferty, NVIDIA
Graham Connor, Imagination
Ben Bowman, Imagination
Jonathan Putsman, Imagination
Piotr Czubak, Intel
Marcin Kantoch, Mobica
Contributors to ARB_texture_buffer_object
Contributors to ARB_texture_buffer_range
Notice
Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Specification Update Policy
Khronos-approved extension specifications are updated in response to
issues and bugs prioritized by the Khronos OpenGL ES Working Group. For
extensions which have been promoted to a core Specification, fixes will
first appear in the latest version of that core Specification, and will
eventually be backported to the extension document. This policy is
described in more detail at
https://www.khronos.org/registry/OpenGL/docs/update_policy.php
Portions Copyright (c) 2013-2014 NVIDIA Corporation.
Status
Approved by the OpenGL ES Working Group
Ratified by the Khronos Board of Promoters on November 7, 2014
Version
Last Modified Date: July 14, 2014
Revision: 2
Number
OpenGL ES Extension #216
Dependencies
OpenGL ES 3.1 and OpenGL ES Shading Language 3.10 are required.
This specification is written against the OpenGL ES 3.1 (March 17,
2014) and OpenGL ES 3.10 Shading Language (March 17, 2014)
Specifications.
This extension interacts with OES_shader_image_atomic.
Overview
This extension provides a new texture type, called a buffer texture.
Buffer textures are one-dimensional arrays of texels whose storage comes
from an attached buffer object. When a buffer object is bound to a
buffer texture, a format is specified, and the data in the buffer object
is treated as an array of texels of the specified format.
The use of a buffer object to provide storage allows the texture data to
be specified in a number of different ways: via buffer object loads
(BufferData), direct CPU writes (MapBuffer), or framebuffer readbacks to
pixel buffer objects (ReadPixels). A buffer object can also be loaded by
transform feedback, which captures
selected transformed attributes of vertices processed by the GL. Several
of these mechanisms do not require an extra data copy, which would be
required when using conventional TexImage-like entry points.
Buffer textures do not support mipmapping, texture lookups with
normalized floating-point texture coordinates, and texture filtering of
any sort.
They can be accessed via single texel fetch operations in programmable
shaders, using a new sampler type and texel fetch function, and
access can be controlled using the same memory barrier operations
as for other texture types.
Buffer textures are treated as (potentially large) one-dimensional
textures; the maximum texture size supported for buffer textures in the
initial implementation of this extension is 2^27 texels (note that this
extension only guarantees support for buffer textures with 2^16 texels,
but we expect most implementations to exceed that substantially). When a
buffer object is attached to a buffer texture, a size is not specified;
rather, the number of texels in the texture is taken by dividing the size
of the buffer object by the size of each texel.
This extension also allows a sub-range of the buffer's data store to
be attached to a texture. This can be used, for example, to allow multiple
buffer textures to be backed by independent sub-ranges of the same buffer
object, or for different sub-ranges of a single buffer object to be used
for different purposes.
New Procedures and Functions
void TexBufferOES(enum target, enum internalformat, uint buffer);
void TexBufferRangeOES(enum target, enum internalformat, uint buffer,
intptr offset, sizeiptr size);
New Tokens
Accepted by the <target> parameter of BindBuffer, BufferData,
BufferSubData, MapBufferRange, BindTexture, UnmapBuffer,
GetBufferParameteriv, GetBufferPointerv, TexBufferOES, and
TexBufferRangeOES:
TEXTURE_BUFFER_OES 0x8C2A
Accepted by the <pname> parameters of GetBooleanv, GetFloatv, and
GetIntegerv:
TEXTURE_BUFFER_BINDING_OES 0x8C2A
(note that this token name is an alias for TEXTURE_BUFFER_OES,
and is used for naming consistency with queries for the buffers
bound to other buffer binding points).
MAX_TEXTURE_BUFFER_SIZE_OES 0x8C2B
TEXTURE_BINDING_BUFFER_OES 0x8C2C
TEXTURE_BUFFER_OFFSET_ALIGNMENT_OES 0x919F
Returned in the <type> parameter of GetActiveUniform, the <params>
parameter of GetActiveUniformsiv, and the <params> parameter of
GetProgramResourceiv when the TYPE property is queried on the
UNIFORM interface:
SAMPLER_BUFFER_OES 0x8DC2
INT_SAMPLER_BUFFER_OES 0x8DD0
UNSIGNED_INT_SAMPLER_BUFFER_OES 0x8DD8
IMAGE_BUFFER_OES 0x9051
INT_IMAGE_BUFFER_OES 0x905C
UNSIGNED_INT_IMAGE_BUFFER_OES 0x9067
Accepted by the <pname> parameter of GetTexLevelParameter:
TEXTURE_BUFFER_DATA_STORE_BINDING_OES 0x8C2D
TEXTURE_BUFFER_OFFSET_OES 0x919D
TEXTURE_BUFFER_SIZE_OES 0x919E
Additions to the OpenGL ES 3.1 Specification
Modify section 6.1 "Creating and Binding Buffer Objects"
Add to table 6.1 "Buffer object binding targets":
Target Name Purpose Described in section(s)
------------------ ------------------- -----------------------
TEXTURE_BUFFER_OES Texture data buffer 8.8tbo
Modify section 7.3 "Program Objects"
Add to table 7.3 "OpenGL ES Shading Language type tokens...":
Type Name Token Keyword
--------------------------------------- ---------------------------
SAMPLER_BUFFER_OES samplerBuffer
INT_SAMPLER_BUFFER_OES isamplerBuffer
UNSIGNED_INT_SAMPLER_BUFFER_OES usamplerBuffer
IMAGE_BUFFER_OES imageBuffer
INT_IMAGE_BUFFER_OES iimageBuffer
UNSIGNED_INT_IMAGE_BUFFER_OES uimageBuffer
Modify section 7.11 "Shader Memory Access"
Change the description of TEXTURE_FETCH_BARRIER_BIT for MemoryBarrier on
p. 116:
* TEXTURE_FETCH_BARRIER_BIT: Texture fetches from shaders, including
fetches from buffer object memory via buffer textures, after the
barrier will reflect data written by shaders prior to the barrier.
Modify chapter 8 "Textures and Samplers"
Add to the fourth paragraph of the section, on p. 128:
... six faces of the cube. Buffer textures are special one-dimensional
textures whose texel arrays are stored in separate buffer objects.
Modify section 8.1 "Texture Objects"
Change the first paragraph of the section on p. 129:
... The default texture object is bound to each of the TEXTURE_2D,
TEXTURE_3D, TEXTURE_2D_ARRAY, TEXTURE_CUBE_MAP, TEXTURE_2D_MULTISAMPLE,
and TEXTURE_BUFFER_OES targets ...
Change the paragaph following the description of IsTexture on p. 131:
The texture object name space, including the initial two-, and three-
dimensional, two-dimensional array, cube map, two-dimensional
multisample, and buffer texture objects, is shared among all texture
units. ...
Add new section 8.8tbo following section 8.8 "Multisample Textures":
8.8tbo Buffer Textures
In addition to the types of textures described in previous sections, one
additional type of texture is supported. A <buffer texture> is a
one-dimensional texture, consisting of a one-dimensional texel array.
Unlike other texture types, the texel array is not stored as part of the
texture. Instead, a buffer object is attached to a buffer texture and
the texel array is taken from that buffer object's data store. When the
contents of a buffer object's data store are modified, those changes are
reflected in the contents of any buffer texture to which the buffer
object is attached. Buffer textures do not have multiple image levels;
only a single data store is available.
The command
void TexBufferRangeOES(enum target, enum internalformat, uint buffer,
intptr offset, sizeiptr size);
attaches the range of the storage for the buffer object named <buffer>
for <size> basic machine units, starting at <offset> (also in basic
machine units) to the active buffer texture, and specifies an internal
format for the texel array found in the range of the attached buffer
object. If <buffer> is zero, then any buffer object attached to the
buffer texture is detached, the values <offset> and <size> are ignored
and the state for <offset> and <size> for the buffer texture are reset
to zero. <target> must be TEXTURE_BUFFER_OES. <internalformat> specifies
the storage format and must be one of the sized internal formats found
in Table texbo.1.
Errors
An INVALID_ENUM error is generated if <target> is not
TEXTURE_BUFFER_OES.
An INVALID_ENUM error is generated if <internalformat> is not one of the
sized internal formats found in Table texbo.1.
An INVALID_OPERATION error is generated if <buffer> is non-zero, but is
not the name of an existing buffer object.
An INVALID_VALUE error is generated if <offset> is negative, if <size>
is less than or equal to zero, or if <offset> + <size> is greater than
the value of BUFFER_SIZE for the buffer bound to <target>.
An INVALID_VALUE error is generated if <offset> is not an integer
multiple of the value of TEXTURE_BUFFER_OFFSET_ALIGNMENT_OES.
The command
void TexBufferOES(enum target, enum internalformat, uint buffer);
is equivalent to
TexBufferRangeOES(target, internalformat, buffer, 0, size);
with <size> set to the value of BUFFER_SIZE for <buffer>.
When a range of the storage of a buffer object is attached to a buffer
texture, the range of the buffer's data store is taken as the texture's
texel array. The number of texels in the buffer texture's texel array is
given by
floor(<size> / (<components> * sizeof(<base_type>)),
where <components> and <base_type> are the element count and base data
type for elements, as specified in Table texbo.1.
The number of texels in the texel array is then clamped to the value of
the implementation-dependent limit MAX_TEXTURE_BUFFER_SIZE_OES. When a
buffer texture is accessed in a shader, the results of a texel fetch are
undefined if the specified texel coordinate is negative, or greater than
or equal to the clamped number of texels in the texel array.
When a buffer texture is accessed in a shader, an integer is provided to
indicate the texel coordinate being accessed. If no buffer object is
bound to the buffer texture, the results of the texel access are
undefined. Otherwise, the attached buffer object's data store is
interpreted as an array of elements of the GL data type corresponding to
<internalformat>. Each texel consists of one to four elements that are
mapped to texture components (R, G, B, and A). Element <m> of the texel
numbered <n> is taken from element <n> * <components> + <m> of the
attached buffer object's data store. Elements and texels are both
numbered starting with zero. For texture formats with signed or unsigned
normalized fixed-point components, the extracted values are converted to
floating-point values using equations 2.2 or 2.1 respectively. The
components of the texture are then converted to an (R,G,B,A) vector
according to Table texbo.1, and returned to the shader as a
four-component result vector with components of the appropriate data
type for the texture's internal format. The base data type, component
count, normalized component information, and mapping of data store
elements to texture components is specified in Table texbo.1.
Component
Sized Internal Format Base Type Components Norm 0 1 2 3
--------------------- --------- ---------- ---- ---------
R8 ubyte 1 Yes R 0 0 1
R16F half 1 No R 0 0 1
R32F float 1 No R 0 0 1
R8I byte 1 No R 0 0 1
R16I short 1 No R 0 0 1
R32I int 1 No R 0 0 1
R8UI ubyte 1 No R 0 0 1
R16UI ushort 1 No R 0 0 1
R32UI uint 1 No R 0 0 1
RG8 ubyte 2 Yes R G 0 1
RG16F half 2 No R G 0 1
RG32F float 2 No R G 0 1
RG8I byte 2 No R G 0 1
RG16I short 2 No R G 0 1
RG32I int 2 No R G 0 1
RG8UI ubyte 2 No R G 0 1
RG16UI ushort 2 No R G 0 1
RG32UI uint 2 No R G 0 1
RGB32F float 3 No R G B 1
RGB32I int 3 No R G B 1
RGB32UI uint 3 No R G B 1
RGBA8 ubyte 4 Yes R G B A
RGBA16F half 4 No R G B A
RGBA32F float 4 No R G B A
RGBA8I byte 4 No R G B A
RGBA16I short 4 No R G B A
RGBA32I int 4 No R G B A
RGBA8UI ubyte 4 No R G B A
RGBA16UI ushort 4 No R G B A
RGBA32UI uint 4 No R G B A
Table texbo.1, Internal Formats for Buffer Textures. For each
format, the data type of each element is indicated in the "Base
Type" column and the element count is in the "Components" column.
The "Norm" column indicates whether components should be treated as
normalized floating-point values. The "Component 0, 1, 2, and 3"
columns indicate the mapping of each element of a texel to texture
components.
In addition to attaching buffer objects to textures, buffer objects can
be bound to the buffer object target named TEXTURE_BUFFER_OES, in order
to specify, modify, or read the buffer object's data store. The buffer
object bound to TEXTURE_BUFFER_OES has no effect on rendering. A buffer
object is bound to TEXTURE_BUFFER_OES by calling BindBuffer with
<target> set to TEXTURE_BUFFER_OES, as described in chapter 6.
Modify section 8.10.3 "Texture Level Parameter Queries"
Modify the second and third paragraphs in the description of
GetTexLevelParameter*, on p. 173:
"<target> may be ... TEXTURE_2D_ARRAY, TEXTURE_BUFFER_OES, one of the
cube map face ... indicating the ... two-dimensional array texture,
buffer texture, one of the six distinct ...
<lod> determines which level-of-detail's state is returned. If <target>
is TEXTURE_BUFFER_OES, <lod> must be zero."
Modify section 8.18 "Texture State"
Change the first paragraph of the section on p. 191:
... Each array has associated with it a width, height (except for buffer
textures), and depth ... a boolean describing whether the image is
compressed or not, an integer size of a compressed image, and an integer
containing the name of a buffer object bound as the data store of the
image.
Each inital texel array is null ... the compressed flag set to FALSE, a
zero compressed size, and the bound buffer object name is zero.
Buffer textures also contain two pointer sized integers containing the
offset and range of the buffer object's data store.
Modify section 8.22 "Texture Image Loads and Stores"
On p. 197 in the errors section for BindImageTexture, replace the
last error with the following:
An INVALID_OPERATION error is generated if <texture> is neither the
name of a buffer texture, nor the name of an immutable texture object.
Add to table 8.26 "Mapping of image load, store..."
Texture target face/
i j k layer
-------------------------- -- -- -- -----
TEXTURE_BUFFER_OES x - - -
New State
Add to table 20.8 "Textures (selector, state per texture unit)"
Initial
Get Value Type Get Command Value Description Sec.
---------------------------------- -------- ----------- ---------- ---------------------------- -----
TEXTURE_BINDING_BUFFER_OES 48* x Z+ GetIntegerv 0 Texture object bound 8.1
to TEXTURE_BUFFER_OES
Add to table 20.10 "Textures (state per texture image)"
Initial
Get Value Type Get Command Value Description Sec.
------------------------------------- ----- -------------------- ------- --------------------------- --------
TEXTURE_BUFFER_DATA_STORE_BINDING_OES Z+ GetTexLevelParameter 0 Buffer object bound to the 8.8tbo
data store for the active
image unit's buffer texture
TEXTURE_BUFFER_OFFSET_OES n x Z GetTexLevelParameter 0 Offset into buffer's data 8.8tbo
store used for the active
image unit's buffer texture
TEXTURE_BUFFER_SIZE_OES n x Z GetTexLevelParameter 0 Size of the buffer's data 8.8tbo
store used for the active
image unit's buffer texture
Modify the TEXTURE_INTERNAL_FORMAT entry in table 20.10
Initial
Get Value Type Get Command Value Description Sec.
---------------------- ---- -------------------- ------- --------------------------- ------
TEXTURE_INTERNAL_FORMAT E GetTexLevelParameter RGBA Internal format[fn1] 8
or R8
[fn1] The initial internal format is R8 for texture buffer object
images, RGBA for all other texture images.
Add to table 20.50 "Miscellaneous"
Initial
Get Value Type Get Command Value Description Sec.
-------------------------- ---- ----------- ------- --------------------------- ----
TEXTURE_BUFFER_BINDING_OES Z+ GetIntegerv 0 Buffer object bound to 6.1
generic buffer texture
binding point
New Implementation Dependent State
Add to table 20.41 "Implementation Dependent Values (cont.)"
Minimum
Get Value Type Get Command Value Description Sec.
----------------------------------- ---- ----------- ------- --------------------- --------
MAX_TEXTURE_BUFFER_SIZE_OES Z+ GetIntegerv 65536 No. of addressable 8.8tbo
texels for buffer
textures
TEXTURE_BUFFER_OFFSET_ALIGNMENT_OES Z+ GetIntegerv 256 (**) Minimum required 8.8tbo
alignment for texture
buffer offsets
(**) the value of TEXTURE_BUFFER_OFFSET_ALIGNMENT_OES is the largest
allowed value. Smaller values are permitted.
Modifications to the OpenGL ES Shading Language Specification, Version 3.10
#extension GL_OES_texture_buffer: <behavior>
The above line is needed to control the GLSL features described in
this section.
A new preprocessor #define is added to the OpenGL ES Shading Language:
#define GL_OES_texture_buffer 1
Add the following keywords to section 3.7 "Keywords" on p. 14 and
remove them from the list of reserved keywords on p. 15:
samplerBuffer
isamplerBuffer
usamplerBuffer
imageBuffer
iimageBuffer
uimageBuffer
Add to section 4.1 "Basic Types"
Add to table "Floating Point Sampler Types (opaque)" on p. 20:
Type Meaning
---------------------- ---------------------------------------
samplerBuffer a handle for accessing a buffer texture
imageBuffer
Add to table "Signed Integer Sampler Types (opaque)" on p. 21:
Type Meaning
----------------------- ----------------------------------------
isamplerBuffer a handle for accessing an integer buffer
iimageBuffer texture
Add to table "Unsigned Integer Sampler Types (opaque)" on p. 21:
Type Meaning
----------------------- ------------------------------------------
usamplerBuffer a handle for accessing an unsigned integer
uimageBuffer buffer texture
Modify section 4.7.4 "Default Precision Qualifiers"
Add the following types to the list of types which have no default
precision qualifiers at the top of p. 65:
samplerBuffer
isamplerBuffer
usamplerBuffer
imageBuffer
iimageBuffer
uimageBuffer
Modify section 8.9 "Texture Functions"
Add at the end of the paragraph starting "In all functions below" on p.
119:
... performing the texture access operation. No <bias> or <lod>
parameters for multisample textures or texture buffers are supported,
because mipmaps are not allowed for these types of textures.
Add to the table of Texture Query Functions in section 8.9.1 on p. 120:
highp int textureSize(gsamplerBuffer sampler)
Add to the table of Texel Lookup Functions in section 8.9.2 on p. 121:
gvec4 texelFetch(gsamplerBuffer sampler, int P)
Modify section 8.14 "Image Functions":
Add to the description of the IMAGE_INFO placeholder in the fourth
paragraph of the section, on p. 132:
The "IMAGE_INFO" in the prototypes below is a placeholder ...
gimage2DArray image, ivec3 coord
gimageBuffer image, int P
Add to the table of image functions on p. 133:
highp int imageSize(readonly writeonly gimageBuffer image)
Change the introduction of section 8.16 "Shader Memory Control
Functions":
Shaders of all types may read and write the contents of textures and
buffer objects using image variables. While the order of reads ...
Dependencies on OES_shader_image_atomic
When OES_shader_image_atomic is supported, all the imageAtomic* functions
are supported on image buffers.
Issues
Note: These issues apply specifically to the definition of the
OES_texture_buffer specification, which is based on the OpenGL
extension ARB_texture_buffer_object as updated in OpenGL 4.x. Resolved
issues from ARB_texture_buffer_object have been removed (with the
exception of issue 6, which is copied from issue 12 of the ARB
extension), but remain largely applicable to this extension.
ARB_texture_buffer_object can be found in the OpenGL Registry.
(1) What functionality was removed from ARB_texture_buffer_object?
- Support for sized buffer formats R16, RG16, and RGBA16, and for
MapBuffer and GetBufferSubData is removed since they do not exist
in ES 3.0.
- Support for ALPHA and LUMINANCE buffer textures is removed since
they are legacy formats in ES 3.0, and there are no sized ALPHA or
LUMINANCE formats.
- GL 4.4 extended support for buffer textures to the
GetInternalformativ query <target>, but that command in ES 3.0 is
restricted to returning multisampling information, which is
irrelevant to buffer textures.
- Support for TEXTURE_BUFFER_FORMAT is removed. Use the
GetTexLevelParameter* TEXTURE_INTERNAL_FORMAT query instead.
(2) What functionality was changed and added relative to
ARB_texture_buffer_object?
- OES_texture_buffer more closely matches OpenGL 4.4 language,
rather than ARB_texture_buffer_object language.
* Support for querying buffer texture state with
GetTexLevelParameter* is added
* Support for sized R, RG, and RGB formats is added. Per issue (2)
of ARB_texture_buffer_object, some formats supported by ES 3.0 but
which may present hardware difficulties are not supported,
including R*8_SNORM and all RGB formats other than RGB32*.
- Interactions were added with OpenGL ES 3.1 and other OES extension
functionality, primarily shader memory access as well as texture
level parameter queries.
- incorporates the ability to bind a sub-range of a buffer from
ARB_texture_buffer_range.
(3) What should the rules on GLSL suffixing be?
RESOLVED: The new sampler and image types are reserved keywords in
ESSL 3.00 so they can be use without prefix/suffixes.
(4) Do we want the ARB_texture_buffer_range functionality present in GL
4.4? This adds useful functionality (backing the buffer texture with
a selected part of a buffer object) at low increase in complexity of
the spec.
RESOLVED: Yes, this functionality is included in this extension.
(5) How is the various buffer texture-related state queried?
There are three pieces of state that can be queried:
(a) the texture object bound to buffer texture binding point for
the active texture image unit (TEXTURE_BINDING_BUFFER_OES).
(b) the buffer object whose data store was used by that texture
object (TEXTURE_BUFFER_DATA_STORE_BINDING_OES).
(c) the buffer object bound to the TEXTURE_BUFFER_OES binding
point (TEXTURE_BUFFER_BINDING_OES).
The first and last are queried with GetIntegerv, but the second is
queried with GetTexLevelParameter. Note that for (a) and (b), the
texture queried is the one bound to TEXTURE_BUFFER_EXT on the active
texture image unit.
(6) Should the R16, RG16 and RGBA16 texture formats be supported?
RESOLVED. No. OpenGL ES 3.0 does not support these formats. They were
considered for late addition to OpenGL ES 3.1 in Bug 11366, but didn't
make the cut. In the absence of another extension to add them, they
are not supported here either.
(7) OpenGL ES 3.1 does not allow images to be created from mutable
textures (ie those created with TexImage). How does this affect
this extension?
RESOLVED. Buffer textures would technically be considered mutable
since they are not defined by a TexStorage command and it is possible
to redefine the buffer storage which backs them. However there is
currently no ES API for creating immutable buffers
(ARB_buffer_storage does this for GL) and thus we must allow mutable
buffers to back buffer textures.
(8) This extension is called OES_texture_buffer, but the desktop name
is {EXT,ARB}_texture_buffer_object. Is the name change intentional?
RESOLVED. Yes. We want to avoid extensions in ES and GL that have the
same name, but not the same functionality (except as a subset).
OES_texture_buffer includes the functionality of ARB_texture_buffer_object,
ARB_texture_buffer_range, and ARB_texture_buffer_rgb32, along with some
changes that were made with how those operate GL 4.4. It would have been
too messy and confusing to try to incorporate all these into the existing
EXT_texture_buffer_object spec from GL as interactions with ES.
Revision History
Rev. Date Author Changes
---- ---------- --------- -------------------------------------------------
2 07/14/2014 dkoch Clarify that TEXTURE_BUFFER_DATA_STORE_BINDING_EXT
is queried with GetTexLevelParameter not
GetIntegerv (Bug 12343). Fix types in unsigned
sampler types table (Bug 12356)
1 06/18/2014 dkoch Initial OES version based on EXT.
No functional changes.
