blob: 9a265169fd6f587b3ff0e5ae785c15ad1bafc3b6 [file] [log] [blame]
Name
ARB_sampler_objects
Name Strings
GL_ARB_sampler_objects
Contact
Graham Sellers, AMD (graham.sellers 'at' amd.com)
Contributors
Graham Sellers, AMD
Jaakko Konttinen, AMD
Jeff Bolz, NVIDIA
Daniel Koch, TransGaming
Bruce Merry, ARM
Notice
Copyright (c) 2010-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 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
Status
Complete. Approved by the ARB at the 2010/01/22 F2F meeting.
Approved by the Khronos Board of Promoters on March 10, 2010.
Version
Version 13, November 12, 2014
Number
ARB Extension #81
Dependencies
This extension is written against the OpenGL 3.2 (Compatibility
Profile) specification.
This extension interacts with EXT_texture_filter_anisotropic.
OpenGL 1.0 is required.
Overview
In unextended OpenGL textures are considered to be sets of image
data (mip-chains, arrays, cube-map face sets, etc.) and sampling
state (sampling mode, mip-mapping state, coordinate wrapping and
clamping rules, etc.) combined into a single object. It is typical
for an application to use many textures with a limited set of
sampling states that are the same between them. In order to use
textures in this way, an application must generate and configure
many texture names, adding overhead both to applications and to
implementations. Furthermore, should an application wish to sample
from a texture in more than one way (with and without mip-mapping,
for example) it must either modify the state of the texture or
create two textures, each with a copy of the same image data. This
can introduce runtime and memory costs to the application.
This extension separates sampler state from texture image data. A
new object type is introduced, the sampler (representing generic
sampling parameters). The new sampler objects are represented by a
new named type encapsulating the sampling parameters of a
traditional texture object. Sampler objects may be bound to texture
units to supplant the bound texture's sampling state. A single
sampler may be bound to more than one texture unit simultaneously,
allowing different textures to be accessed with a single set of
shared sampling parameters. Also, by binding different sampler
objects to texture units to which the same texture has been bound,
the same texture image data may be sampled with different sampling
parameters.
IP Status
No known IP claims.
New Procedures and Functions
void GenSamplers(sizei count, uint *samplers);
void DeleteSamplers(sizei count, const uint * samplers);
boolean IsSampler(uint sampler);
void BindSampler(uint unit, uint sampler);
void SamplerParameteri(uint sampler, enum pname, int param);
void SamplerParameterf(uint sampler, enum pname, float param);
void SamplerParameteriv(uint sampler, enum pname, const int *params);
void SamplerParameterfv(uint sampler, enum pname, const float *params);
void SamplerParameterIiv(uint sampler, enum pname, const int *params);
void SamplerParameterIuiv(uint sampler, enum pname, const uint *params);
void GetSamplerParameteriv(uint sampler, enum pname, int *params);
void GetSamplerParameterfv(uint sampler, enum pname, float *params);
void GetSamplerParameterIiv(uint sampler, enum pname, int *params);
void GetSamplerParameterIuiv(uint sampler, enum pname, uint *params);
New Tokens
Accepted by the <value> parameter of the GetBooleanv, GetIntegerv,
GetInteger64v, GetFloatv and GetDoublev functions:
SAMPLER_BINDING 0x8919
Additions to Chapter 2 of the OpenGL 3.2 Specification (Compatibility Profile) (OpenGL Operation)
None.
Additions to Chapter 3 of the OpenGL 3.2 Specification (Compatibility Profile) (Rasterization)
Additions to Section 3.8.12 Texture Completeness
Add subheading "Effects of Sampler Objects on Texture Completeness"
If a sampler object and a texture object are simultaneously bound to
the same texture unit, then the sampling state for that unit is
taken from the sampler object (see section 3.9.2, "Sampler
Objects"). This can have an effect on the effective completeness of
the texture. In particular, if the texture is not mipmap complete
and the sampler object specifies a MIN_FILTER requiring mipmaps, the
texture will be considered incomplete for the purposes of that
texture unit. However, if the sampler object does not require
mipmaps, the texture object will be considered complete. This means
that a texture can be considered both complete and incomplete
simultaneously if it is bound to two or more texture units along
with sampler objects with different states.
Additions to Section 3.9 Texturing
Modify the prologue to Section 3.9 as follows:
Renumber Section 3.9.14 "Texture Objects" to Section 3.9.1. renumber
subsequent sections
Replace Section 3.9.1 "Texture Objects"
3.9.1 Texture Objects
---------------------
Textures in GL are represented by named objects. The name space for
texture objects is the unsigned integers, with zero reserved by the
GL to represent the default texture object. The default texture
object is bound to each of the TEXTURE_1D, TEXTURE_2D, TEXTURE_3D,
TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, TEXTURE_RECTANGLE,
TEXTURE_BUFFER, TEXTURE_CUBE_MAP, TEXTURE_2D_MULTISAMPLE, and
TEXTURE_2D_MULTISAMPLE_ARRAY targets during context initialization.
A new texture object is created by binding an unused name to one of
these texture targets. The command
void GenTextures( sizei n, uint *textures );
returns <n> previously unused texture names in <textures>. These
names are marked as used, for the purposes of GenTextures only, but
they acquire texture state and a dimensionality only when they are
first bound, just as if they were unused. The binding is effected by
calling
void BindTexture( enum target, uint texture );
with <target> set to the desired texture target and <texture> set to
the unused name. The resulting texture object is a new state vector,
comprising all the state and with the same initial values listed in
section 3.9.13. The new texture object bound to <target> is, and
remains a texture of the dimensionality and type specified by
<target> until it is deleted.
BindTexture may also be used to bind an existing texture object to
any of these targets. The error INVALID_OPERATION is generated if an
attempt is made to bind a texture object of different dimensionality
than the specified <target>. If the bind is successful no change is
made to the state of the bound texture object, and any previous
binding to <target> is broken.
** This error applies only to 3.2 core profile / 3.1 w/o ARB_compatibility /
** 3.0 deprecated contexts.
BindTexture fails and an INVALID_OPERATION error is generated if
<texture> is not zero or a name returned from a previous call to
GenTextures, or if such a name has since been deleted. While a
texture object is bound, GL operations on the target to which it is
bound affect the bound object, and queries of the target to which it
is bound return state from the bound object. If texture mapping of
the dimensionality of the target to which a texture object is bound
is enabled, the state of the bound texture object directs the
texturing operation.
Texture objects are deleted by calling
void DeleteTextures( sizei n, uint *textures );
<textures> contains <n> names of texture objects to be deleted.
After a texture object is deleted, it has no contents or
dimensionality, and its name is again unused. If a texture that is
currently bound to any of the target bindings of BindTexture is
deleted, it is as though BindTexture had been executed with the same
target and texture zero. Additionally, special care must be taken
when deleting a texture if any of the images of the texture are
attached to a framebuffer object. See section 4.4.2 for details.
Unused names in <textures> are silently ignored, as is the name zero.
The texture object name space, including the initial one-, two-, and
three- dimensional, one- and two-dimensional array, rectangular,
buffer, cube map, two-dimensional multisample, and two-dimensional
multisample array texture objects, is shared among all texture
units. A texture object may be bound to more than one texture unit
simultaneously. After a texture object is bound, any GL operations
on that target object affect any other texture units to which the
same texture object is bound.
Texture binding is affected by the setting of the state
ACTIVE_TEXTURE. If a texture object is deleted, it as if all texture
units which are bound to that texture object are rebound to texture
object zero.
Insert new Section 3.9.2 "Sampler Objects", renumber subsequent
sections.
3.9.2 Sampler Objects
---------------------
The state necessary for texturing can be divided into two categories
as described in Section 3.9.13. An OpenGL texture object represents
both sets. The first set represents dimensionality and other image
parameters, and the second set represents sampling state.
Additionally, a sampler object may be created to encapsulate only
the second set, or the sampling state, of a texture object.
A new sampler object is created by binding an unused name to a
texture unit. The command
void GenSamplers( sizei count, uint *samplers );
returns <count> previously unused sampler object names in
<samplers>. The name zero is reserved by the GL to represent no
sampler being bound to a sampler unit. The names are marked as used,
for the purposes of GenSamplers only, but they acquire state only
when they are first used as a parameter to BindSampler,
SamplerParameter*, GetSamplerParameter*, or IsSampler. When a
sampler object is first used in one of these functions, the
resulting sampler object is initialized with a new state vector,
comprising all the state and with the same initial values listed in
table 6.23.
When a sampler object is bound to a texture unit, its state
supersedes that of the texture object bound to that texture unit. If
the sampler name zero is bound to a texture unit, the currently
bound texture's sampler state becomes active. A single sampler
object may be bound to multiple texture units simultaneously.
A sampler binding is effected by calling
void BindSampler( uint unit, uint sampler );
with <unit> set to the texture unit to which to bind the sampler and
<sampler> set to the name of a sampler object returned from a
previous call to GenSampler.
<unit> must be between zero and the value of
MAX_TEXTURE_IMAGE_UNITS-1. <sampler> is the name of a sampler object
that has previously been reserved by a call to GenSamplers.
If the bind is successful no change is made to the state of the
bound sampler object, and any previous binding to <unit> is broken.
BindSampler fails and an INVALID_OPERATION error is generated if
<sampler> is not zero or a name returned from a previous call to
GenSamplers, or if such a name has since been deleted with
DeleteSamplers. An INVALID_VALUE error is generated if <unit> is
greater than or equal to the value of
MAX_COMBINED_TEXTURE_IMAGE_UNITS.
If state is present in a sampler object bound to a texture unit that
would have been rejected by a call to TexParameter for the texture
bound to that unit, the behavior of the implementation is as if the
texture were incomplete. For example, if TEXTURE_WRAP_S,
TEXTURE_WRAP_T or TEXTURE_WRAP_R is set to REPEAT or MIRRORED_REPEAT
on the sampler object bound to a texture unit and the texture bound
to that unit is a TEXTURE_RECTANGLE, the texture will be considered
incomplete.
The currently bound sampler may be queried by calling GetIntegerv
with <pname> set to SAMPLER_BINDING. When a sampler object is
unbound from the texture unit (by binding another sampler object, or
the sampler object named zero, to that texture unit) the modified
state is again replaced with the sampler state associated with the
texture object bound to that texture unit.
The parameters represented by a sampler object are a subset of those
described in Section 3.9.6 "Texture Parameters". Each parameter of a
sampler object is set by calling
void SamplerParameter{if}{v}( uint sampler, enum pname, T param );
void SamplerParameterI{u ui}v( uint sampler, enum pname, T *params );
<sampler> is the name of a sampler object previously reserved by a
call to GenSamplers. <pname> is the name of a parameter to modify
and <param> is the new value of that parameter. An INVALID_OPERATION
error is generated if <sampler> is not the name of a sampler object
previously returned from a call to GenSamplers. The values accepted
in the <pname> parameter are TEXTURE_WRAP_S, TEXTURE_WRAP_T,
TEXTURE_WRAP_R, TEXTURE_MIN_FILTER, TEXTURE_MAG_FILTER,
TEXTURE_BORDER_COLOR, TEXTURE_MIN_LOD, TEXTURE_MAX_LOD,
TEXTURE_LOD_BIAS, TEXTURE_COMPARE_MODE, TEXTURE_COMPARE_FUNC and
TEXTURE_MAX_ANISOTROPY_EXT. Texture state listed in table 6.22 but
not listed here and in the sampler state in table 6.23 is not part
of the sampler state, and remains in the texture object.
If the values for TEXTURE_BORDER_COLOR are specified with a call to
SamplerParameterIiv or SamplerParameterIuiv, the values are
unmodified and stored with an internal data type of integer. If
specified with SamplerParameteriv, they are converted to
floating-point using equation 2.2. Otherwise, the values are
unmodified and stored as floating-point.
An INVALID_ENUM error is generated if <pname> is not the name of a
parameter accepted by SamplerParameter*. If the value of <param> is
not an acceptable value for the parameter specified in <pname>, an
error is generated as specified in the description of TexParameter*.
Modifying a parameter of a sampler object affects all texture units
to which that sampler object is bound. Calling TexParameter has no
effect on the sampler object bound to the active texture unit. It
will modify the parameters of the texture object bound to that unit.
Sampler objects are deleted by calling
void DeleteSamplers( sizei count, const uint *samplers );
<samplers> contains <count> names of sampler objects to be deleted.
After a sampler object is deleted, its name is again unused. If a
sampler object that is currently bound to a sampler unit is deleted,
it is as though BindSampler is called with <unit> set to the unit
the sampler is bound to and <sampler> zero. Unused names in
<samplers> are silently ignored, as is the reserved name zero.
Additions to Chapter 4 of the OpenGL 3.2 Specification (Compatibility Profile) (Per-Fragment Operations and the Framebuffer)
None.
Additions to Chapter 5 of the OpenGL 3.2 Specification (Compatibility Profile) (Special Functions)
Add a new category of commands not usable in display lists
to section 5.4.1:
"Sampler objects: GenSamplers and DeleteSamplers."
Additions to Chapter 6 of the OpenGL 3.2 Specification (Compatibility Profile) (State and State Requests)
Insert new section 6.1.5 "Sampler Queries" following existing
section 6.1.4 and renumber following sections:
6.1.5 Sampler Queries
The command
boolean IsSampler( uint sampler );
may be called to determine whether <sampler> is the name of a
sampler object IsSampler will return TRUE if <sampler> is the name
of a sampler object previously returned from a call to GenSamplers
and FALSE otherwise. Zero is not the name of a sampler object. The
current values of the parameters of a sampler object may be queried
by calling
void GetSamplerParameter{if}v( uint sampler, enum pname, T *params );
void GetSamplerParameterI{i ui}v( uint sampler, enum pname, T *params );
<sampler> is the name of the sampler object from which to retrieve
parameters. <pname> is the name of the parameter whose value to
retrieve and <params> is the address of an array into which the
current value of the desired parameter will be placed.
GetSamplerParameter* accepts the same values for <pname> as
SamplerParameter*. An INVALID_OPERATION error is generated if
<sampler> is not the name of a sampler object previously returned
from a call to GenSamplers. An INVALID_ENUM error is generated if
<pname> is not the name of a parameter accepted by
GetSamplerParameter*.
Querying value TEXTURE_BORDER_COLOR with GetSamplerParameterIiv or
GetSamplerParameterIuiv returns the border color values as signed
integers or unsigned integers, respectively; otherwise the values
are returned as described in section 6.1.2. If the border color is
queried with a type that does not match the original type with which
it was specified, the result is undefined.
In section 6.1.19, append to the paragraph starting "When PushAttrib
is called with TEXTURE_BIT set...":
"... are restored to their pushed values. The bindings and state for
sampler objects are not pushed or popped."
Additions to Appendix A of the OpenGL 3.2 Specification (Compatibility Profile) (Invariance)
None.
Interactions with EXT_texture_filter_anisotropic
If EXT_texture_filter_anisotropic is not supported, remove all
references to TEXTURE_MAX_ANISOTROPY_EXT.
Additions to the AGL/GLX/WGL Specifications
None.
GLX Protocol
None.
Errors
INVALID_OPERATION is generated by BindSampler if <sampler> is not
zero or a name returned from a previous call to GenSamplers.
INVALID_VALUE is generated by BindSampler if <unit> is greater than
MAX_TEXTURE_IMAGE_UNITS-1.
INVALID_OPERATION is generated by SamplerParameter* and
GetSamplerParameter* if <sampler> is not a name returned from a
previous call to GenSamplers.
New State
Append to Table 6.20, "Textures (state per texture unit and binding point)"
+-----------------------+-----------+-------------------+-----------------+-------------------------+--------+------------+
| Get Value | Type | Get Command | Initial Value | Description | Sec | Attribute |
+-----------------------+-----------+-------------------+-----------------+-------------------------+--------+------------+
| SAMPLER_BINDING | 48* x Z+ | GetIntegerv | 0 | Sampler object bound | 3.9.2 | - |
| | | | | to active texture unit | | |
+-----------------------+-----------+-------------------+-----------------+-------------------------+--------+------------+
Add new Table 6.23, "Textures (state per sampler object)", renumber subsequent tables.
+---------------------------+-----------+----------------------+------------------------+------------------------------+--------+------------+
| Get Value | Type | Get Command | Initial Value | Description | Sec | Attribute |
+---------------------------+-----------+----------------------+------------------------+------------------------------+--------+------------+
| TEXTURE_BORDER_COLOR | n x C | GetSamplerParameter | 0,0,0,0 | Border color | 3.9 | - |
| TEXTURE_MIN_FILTER | n x Z6 | GetSamplerParameter | NEAREST_MIPMAP_LINEAR | Minification function | 3.9.9 | - |
| TEXTURE_MAG_FILTER | n x Z2 | GetSamplerParameter | LINEAR | Magnification function | 3.9.10 | - |
| TEXTURE_WRAP_S | n x Z5 | GetSamplerParameter | REPEAT | Texcoord s wrap mode | 3.9.9 | - |
| TEXTURE_WRAP_T | n x Z5 | GetSamplerParameter | REPEAT | Texcoord t wrap mode | 3.9.9 | - |
| TEXTURE_WRAP_R | n x Z5 | GetSamplerParameter | REPEAT | Texcoord r wrap mode | 3.9.9 | - |
| TEXTURE_MIN_LOD | n x R | GetSamplerParameter | -1000 | Minimum level of detail | 3.9 | - |
| TEXTURE_MAX_LOD | n x R | GetSamplerParameter | 1000 | Maximum level of detail | 3.9 | - |
| TEXTURE_LOD_BIAS | n x R | GetSamplerParameter | 0.0 | Texture level of detail | 3.9.9 | - |
| | | | | bias (biastexobj) | | |
| TEXTURE_COMPARE_MODE | n x Z2 | GetSamplerParameter | NONE | Comparison mode | 3.9.16 | - |
| TEXTURE_COMPARE_FUNC | n x Z8 | GetSamplerParameter | LEQUAL | Comparison function | 3.9.16 | - |
| TEXTURE_MAX_ANISOTROPY_EXT| n x R | GetSamplerParameter | 1.0 | Maximum degree of anisotropy | 3.9 | - |
+---------------------------+-----------+----------------------+------------------------+------------------------------+--------+------------+
New Implementation Dependent State
None.
Issues
1) Should BindSampler take a <target> parameter?
DISCUSSION: Currently it does not. Binding a sampler to a texture
unit binds it to all targets. Binding a texture to a target of a
texture unit continues to determine the target precedence.
2) What is the set of state associated with a sampler object?
Specifically, should TEXTURE_BASE_LEVEL and TEXTURE_MAX_LEVEL be
part of the sampler or the texture?
DISCUSSION: TEXTURE_BASE_LEVEL and TEXTURE_MAX_LEVEL are presently
part of the image state (texture) and are thus not included in the
sampler object. TEXTURE_WRAP_S, TEXTURE_WRAP_T, TEXTURE_WRAP_R,
TEXTURE_MIN_FILTER, TEXTURE_MAG_FILTER, TEXTURE_BORDER_COLOR,
TEXTURE_MIN_LOD, TEXTURE_MAX_LOD, TEXTURE_LOD_BIAS,
TEXTURE_COMPARE_MODE, TEXTURE_COMPARE_FUNC are the states included
in the sampler object.
3) How would one use the same sampler state to access multiple
textures?
DISCUSSION: Generate a sampler object, set its state. Then, bind the
same sampler object to multiple texture units (perhaps with
different textures bound to them) and use those units as usual.
4) How would one access the same texture with different samplers?
DISCUSSION: Generate a sampler object for each intended set of
sampling parameters and bind them to different texture units. Bind
the same texture to each of those units. That same texture will be
sampled according to the parameters contained in the sampler object
bound to the respective unit.
5) Does it matter what order samplers and textures are bound to
texture units?
No. As long as a sampler is bound to a texture unit, it acts as the
source of the sampler state for that unit. Textures may be switched
in and out without affecting the sampler state. This includes the
default texture object.
6) If a sampler object is bound to multiple texture units and its
state is modified, is that state visible to all of those units?
Yes.
7) Should sampler objects be made visible to the shading language.
This is left for a future extension. Separating samplers and texture
images in the shader allows for a run-time combinatorial explosion
of sampler- texture pairs that would be difficult to count. It is
also very clumsy to specify in a way that interacts cleanly with
prior versions of OpenGL. This may become more feasible to apply
against a future version of OpenGL, but this extension is applicable
to any version of OpenGL.
8) Can sampler objects be shared between contexts?
Yes. The semantics of sharing a sampler object between contexts is
the same as that of sharing texture objects.
9) What happens when a sampler object bound to a texture unit has a
parameter that is incompatible with the texture that is bound to
that unit?
The behavior is as if the texture is incomplete.
10) When are sampler objects created? When do they start to exist?
Sampler objects are created when they are first used by any function
taking the name of a sampler object as a parameter. Their names must
be reserved by a call to GenSamplers. For all intents and purposes,
it is as if they start existing when GenSamplers creates their
names.
Revision History
Rev. Date Author Changes
---- ---------- --------- -----------------------------------------
13 11/12/2014 Jon Leech Fix spelling of TEXTURE_MAX_ANISOTROPY
(public Bug 1263).
12 07/22/2011 Jon Leech Fix valid <unit> values to be based
on MAX_COMBINED_TEXTURE_IMAGE_UNITS
instead of MAX_TEXTURE_IMAGE_UNITS (bug
6406).
11 07/07/2010 Jon Leech Do not allow sampler bindings and sampler
object state to be pushed and popped, by
modifying all new state table entries to
have no attribute group and adding a
clarifying statement in section 6.1.20.
Do not allow GenSamplers and
DeleteSamplers in display lists (bug
6056).
10 03/29/2010 pbrown Further fixes in the listed prototypes;
use separate lines for external parsing.
9 03/27/2010 pbrown Fix an incorrect prototype for BindSampler
in the new functions section (bug 6146).
8 03/22/2010 Jon Leech Change error for invalid <sampler> names
passed to *SamplerParameter* from
INVALID_VALUE to INVALID_OPERATION for
consistency (bug 6026). Expand Errors
section. Reformat to 80 columns.
7 02/10/2010 Jon Leech Add const to SamplerParameter*v 'params'.
6 01/26/2010 pbrown Assign enum for SAMPLER_BINDING.
5 01/05/2010 gsellers Add SamplerParameterI*, GetSamplerParameterI*
(bug 5806).
Fix ambiguity about when sampler objects
are created. Samplers names are reserved
by GenSamplers but actually created
(default state initialized) on first
use. There is no bind-to-create for
sampler objects. (bug 5813).
Add language about effect of sampler
objects on effective texture
completeness (bug 5838). Specify that
illegal sampler states for particular
texture types result in incomplete
textures, rather than undefined
behavior.
4 12/11/2009 Jon Leech Reorganization and consistency edits
resulting from 3.3 spec integration.
Remove ARB suffixes.
3 11/19/2009 gsellers Feedback from bmerry.
2 11/11/2009 gsellers Incorporate feedback.
1 11/09/2009 gsellers Initial version based on draft
EXT_separate_sampler_objects.