Name
OES_texture_border_clamp
Name Strings
GL_OES_texture_border_clamp
Contact
Daniel Koch, NVIDIA (dkoch 'at' nvidia 'dot' com)
Contributors
Jussi Rasanen, NVIDIA
Greg Roth, NVIDIA
Dominik Witczak, Mobica
Graham Connor, Imagination
Ben Bowman, Imagination
Jonathan Putsman, Imagination
Maurice Ribble, Qualcomm
Notice
Copyright (c) 2014 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
Status
Approved by the OpenGL ES Working Group
Ratified by the Khronos Board of Promoters on November 7, 2014
Version
Last Modified Date: June 18, 2014
Revision: 1
Number
OpenGL ES Extension #215
Dependencies
OpenGL ES 2.0 is required.
This extension is written against the OpenGL ES 3.0.2
specification.
OpenGL ES 3.0 affects the definition of this extension.
OES_texture_3D affects the definition of this extension.
EXT_texture_compression_s3tc trivially affects the definition
of this extension.
KHR_texture_compression_astc_{ldr,hdr} trivially affect the
definition of this extension.
Overview
OpenGL ES provides only a single clamping wrap mode: CLAMP_TO_EDGE.
However, the ability to clamp to a constant border color can be
useful to quickly detect texture coordinates that exceed their
expected limits or to dummy out any such accesses with transparency
or a neutral color in tiling or light maps.
This extension defines an additional texture clamping algorithm.
CLAMP_TO_BORDER_OES clamps texture coordinates at all mipmap levels
such that NEAREST and LINEAR filters of clamped coordinates return
only the constant border color. This does not add the ability for
textures to specify borders using glTexImage2D, but only to clamp
to a constant border value set using glTexParameter and
glSamplerParameter.
New Procedures and Functions
void TexParameterIivOES(enum target, enum pname, const int *params);
void TexParameterIuivOES(enum target, enum pname, const uint *params);
void GetTexParameterIivOES(enum target, enum pname, int *params);
void GetTexParameterIuivOES(enum target, enum pname, uint *params);
void SamplerParameterIivOES(uint sampler, enum pname, const int *params);
void SamplerParameterIuivOES(uint sampler, enum pname, const uint *params);
void GetSamplerParameterIivOES(uint sampler, enum pname, int *params);
void GetSamplerParameterIuivOES(uint sampler, enum pname, uint *params);
New Tokens
Accepted by the <pname> parameter of TexParameteriv, TexParameterfv,
SamplerParameteriv, SamplerParameterfv, TexParameterIivOES,
TexParameterIuivOES, SamplerParameterIivOES, SamplerParameterIuivOES,
GetTexParameteriv, GetTexParameterfv, GetTexParameterIivOES,
GetTexParameterIuivOES, GetSamplerParameteriv, GetSamplerParameterfv,
GetSamplerParameterIivOES, and GetSamplerParameterIuivOES:
TEXTURE_BORDER_COLOR_OES 0x1004
Accepted by the <param> parameter of TexParameteri, TexParameterf,
SamplerParameteri and SamplerParameterf, and by the <params> parameter of
TexParameteriv, TexParameterfv, TexParameterIivOES, TexParameterIuivOES,
SamplerParameterIivOES, SamplerParameterIuivOES and returned by the
<params> parameter of GetTexParameteriv, GetTexParameterfv,
GetTexParameterIivOES, GetTexParameterIuivOES, GetSamplerParameteriv,
GetSamplerParameterfv, GetSamplerParameterIivOES, and
GetSamplerParameterIuivOES when their <pname> parameter
is TEXTURE_WRAP_S, TEXTURE_WRAP_T, or TEXTURE_WRAP_R:
CLAMP_TO_BORDER_OES 0x812D
Note that the {Get}TexParameterI{i ui}vOES and
{Get}SamplerParameterI{i ui}vOES functions also accept all the
same parameters and values as are accepted by the existing
{Get}TexParameter{if}v and {Get}SamplerParameter{if}v commands,
respectively.
Additions to Chapter 3 of the OpenGL ES 3.0.2 Specification
(Rasterization)
Modifications to Section 3.8.2 "Sampler Objects"
Add the following to the list of SamplerParameter commands (p.123):
void SamplerParameterI{i ui}vOES(uint sampler, enum pname,
const T *params);
Modify the last sentence of the description of the commands to state:
"In the first form of the command, <param> is a value to which to
set a single-valued parameter; in the remaining forms, <params> is an
array of parameters whose type depends on the parameter being set."
Replace the last sentence of the 3rd paragraph on p.123 (beginning with
"The values accepted in the <pname> parameter..." with the following:
"<pname> must be one of the sampler state names in Table 6.10, otherwise
an INVALID_ENUM error is generated. An INVALID_ENUM error is generated
if SamplerParameter{if} is called for a non-scalar parameter
(TEXTURE_BORDER_COLOR_OES)."
Replace the 4th paragraph on p.123 (beginning with "Data conversions...")
with the following:
"Data conversions are performed as specified in section 2.3.1, except
that if the values for TEXTURE_BORDER_COLOR_OES 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, border color values are unmodified and stored
as floating-point."
Modifications to Section 3.8.6 "Compressed Texture Images"
Add column to Table 3.16 with heading "Border Type" fill in the
values as follows:
"unorm" for the following compressed internal formats:
COMPRESSED_R11_EAC, COMPRESSED_RG11_EAC, COMPRESSED_RGB8_ETC2,
COMPRESSED_SRGB8_ETC2, COMPRESSED_RGB8_PUNCHTHROUGH_ALPHA1_ETC2,
COMPRESSED_SRGB8_PUNCHTHROUGH_ALPHA1_ETC2, COMPRESSED_RGBA8_ETC2_EAC,
COMPRESSED_SRGB8_ALPHA8_ETC2_EAC,
COMPRESSED_RGB_S3TC_DXT1_EXT, COMPRESSED_RGBA_S3TC_DXT1_EXT,
COMPRESSED_RGBA_S3TC_DXT3_EXT, COMPRESSED_RGBA_S3TC_DXT5_EXT,
COMPRESSED_RGBA_ASTC_*_KHR, COMPRESSED_SRGB8_ALPHA8_ASTC_*_KHR
"snorm" for the following compressed internal formats:
COMPRESSED_SIGNED_R11_EAC, COMPRESSED_SIGNED_RG11_EAC
"float" for the following compressed internal formats:
(currently none -- to be added by any extension adding BPTC support)
Add the following to the table caption:
"The 'Border Type' field determines how border colors are clamped as
described in section 3.8.10."
Modifications to Section 3.8.7 "Texture Parameters"
Add the following to the list of TexParameter commands (p.223):
void TexParameterI{i ui}vOES(enum target, enum pname,
const T *params);
Modify the last sentence of the description of the commands to state:
"In the first form of the command, <param> is a value to which to
set a single-valued parameter; in the remaining forms, <params> is an
array of parameters whose type depends on the parameter being set."
Add a new paragraph at the end of p.145 after the paragraph about data
conversions:
"In addition, if the values for TEXTURE_BORDER_COLOR_OES are specified
with TexParameterIiv or TexParameterIuiv, the values are unmodified and
stored with an internal data type of integer or unsigned integer,
respectively. If specified with TexParameteriv, 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
TexParameter{if} is called for a non-scalar parameters
(TEXTURE_BORDER_COLOR_OES)."
Modify Table 3.17, edit the following rows (adding
CLAMP_TO_BORDER_OES to each of the wrap modes):
Name Type Legal Values
============== ==== ====================
TEXTURE_WRAP_S enum CLAMP_TO_EDGE, REPEAT, MIRRORED_REPEAT,
CLAMP_TO_BORDER_OES
TEXTURE_WRAP_T enum CLAMP_TO_EDGE, REPEAT, MIRRORED_REPEAT,
CLAMP_TO_BORDER_OES
TEXTURE_WRAP_R enum CLAMP_TO_EDGE, REPEAT, MIRRORED_REPEAT,
CLAMP_TO_BORDER_OES
and add the following row:
Name Type Legal Values
============== ======== ====================
TEXTURE_BORDER_COLOR_OES 4 floats, any 4 values
ints, or
uints
Modifications to Section 3.8.9 "Cube Map Texture Selection"
In the "Seamless Cube Map Filtering" subsection change the rule
about LINEAR filtering to state:
"* If LINEAR filtering is done within a miplevel, always apply
wrap mode CLAMP_TO_BORDER_OES. Then, ..."
Modifications to Section 3.8.10 "Texture Minification"
Modify Table 3.19, edit the cell that says:
"border clamping (used only for cube maps with LINEAR filter)"
and replace it with "CLAMP_TO_BORDER_OES".
In the subsection "Coordinate Wrapping and Texel Selection"
add the following text at the end of the description for when
TEXTURE_MIN_FILTER is NEAREST:
"If the selected (i,j,k), (i,j) or i location refers to a border texel
that satisfies any of the conditions:
i < 0, j < 0, k < 0, i >= w_t, j >= h_t, k >= d_t
then the border values defined by TEXTURE_BORDER_COLOR_OES are used
in place of the non-existent texel. If the texture contains color
components, the values of TEXTURE_BORDER_COLOR_OES are interpreted
as an RGBA color to match the texture's internal format in a manner
consistent with table 3.11. The internal data type of the border
colors must be consistent with the type returned by the texture as
described in chapter 3, or the result is undefined. Border values are
clamped before they are used, according to the format in which the
texture components are stored. For signed and unsigned normalized
fixed-point formats, border values are clamped to [-1,1] and [0,1]
respectively. For floating-point and integer formats, border values
are clamped to the representable range of the format. For compressed
formats, border values are clamped as signed normalized ("snorm"),
unsigned normalized ("unorm"), or floating-point as described in
Table 3.16 for each format. If the texture contains depth components,
the first component of TEXTURE_BORDER_COLOR_OES is interpreted as a
depth value."
Add the following text at the end of the description for when
TEXTURE_MIN_FILTER is LINEAR:
"For any texel in the equation above that refers to a border texel
outside the defined range of the image, the texel value is taken
from the texture border color as with NEAREST filtering."
Modifications to Section 3.7.14 "Texture state"
Modify the second paragraph as follows:
"Next, there are four sets of texture properties... Each set consists
of the selected minification and magnification filters, the wrap modes
for s, t, r (three-dimensional only), the TEXTURE_BORDER_COLOR_OES,
two floating-point numbers ... In the initial state, ... wrap modes
are set to REPEAT, and the value of TEXTURE_BORDER_COLOR_OES is
(0,0,0,0). ..."
Additions to Chapter 6 of the OpenGL ES 3.0.2 Specification
(State and State Requests)
Modifications to Section 6.1.3 "Enumerated Queries"
Add the following command in a list with GetTexParameter{if}v:
void GetTexParameterI{i ui}v(enum target, enum pname, T *data);
Append the following to the description of the GetTexParameter* commands:
"Querying <pname> TEXTURE_BORDER_COLOR_OES with GetTexParameterIiv or
GetTexParameterIuiv 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."
Modifications to Section 6.1.5 "Sampler Queries"
Add the following command in a list with GetSamplerParameter{if}v:
void GetSamplerParameterI{i ui}v(uint sampler, enum pname, T *params);
Append the following to the description of the GetSamplerParameter*
commands:
"Querying TEXTURE_BORDER_COLOR_OES 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."
Errors
An INVALID_ENUM error is generated if TexParameter{if} is called for
a non-scalar parameter (TEXTURE_BORDER_COLOR_OES).
An INVALID_ENUM error is generated by TexParameterI*v if
<target> is not one of the valid types of texture targets accepted
by TexParameter{if}v.
An INVALID_ENUM error is generated by TexParameterI*v if <pname>
is not one of the values listed in Table 3.17.
An INVALID_ENUM error is generated by TexParameterI*v if the type
of the parameter specified by <pname> is enum, and the value(s)
specified by <params> is not among the legal values shown in
Table 3.17.
An INVALID_ENUM error is generated by GetTexParameterI*v if
<target> is not one of the valid types of texture targets accepted
by GetTexParameter{if}v.
An INVALID_ENUM error is generated by GetTexParameterI*v if
<pname> is not one of values accepted by GetTexParameter{if}v.
An INVALID_ENUM error is generated if SamplerParameter{if} is called
for a non-scalar parameter (TEXTURE_BORDER_COLOR_OES).
An INVALID_OPERATION error is generated by SamplerParameterI*v
if <sampler> is not the name of a sampler object previously returned
from a call to GenSamplers.
An INVALID_ENUM error is generated by SamplerParameterI*v if
<pname> is not the name of a parameter accepted by SamplerParameter*.
An INVALID_OPERATION error is generated by GetSamplerParameterI*v
if <sampler> is not the name of a sampler object previously returned
from a call to GenSamplers.
An INVALID_ENUM error is generated by GetSamplerParameterI*v if
<pname> is not the name of a parameter accepted by GetSamplerParameter*.
New State
Modify table 6.10:
Change the type information changes for these parameters.
Initial
Get Value Type Get Command Value Description Sec.
--------- ------ ----------- ------- ----------- ----
TEXTURE_WRAP_S n x Z4 GetSamplerParameter (as before...)
TEXTURE_WRAP_T n x Z4 GetSamplerParameter (as before...)
TEXTURE_WRAP_R n x Z4 GetSamplerParameter (as before...)
Add the following parameter:
Get Value Type Get Command Value Description Sec.
--------- ------ ----------- ------- ----------- ----
TEXTURE_BORDER_COLOR_OES 4 x C GetSamplerParameter 0.0,0.0,0.0,0.0 border color 3.8
Dependencies on OpenGL ES 3.0
If OpenGL ES 3.0 is not supported, but OES_texture_3D is supported,
replace references to TEXTURE_WRAP_R with TEXTURE_WRAP_R_OES.
If OpenGL ES 3.0 is not supported, delete all references to the
TexParameterI*, GetTexParameterI*, SamplerParameterI*, and
GetSamplerParameterI* entry points and all related text about
signed and unsigned integer textures.
Dependencies on OES_texture_3D
If neither OpenGL ES 3.0 nor OES_texture_3D is supported, ignore all
references to three-dimensional textures and the token TEXTURE_WRAP_R
as well as any reference to r wrap modes. References to (i,j,k), k,
and d_t in section 3.8.10 should also be removed.
Dependencies on EXT_texture_compression_s3tc
If EXT_texture_compression is not supported, ignore all references to
S3TC compressed textures.
Dependencies on KHR_texture_compression_astc_{ldr,hdr}
If none of the KHR_texture_compression_astc extensions are supported,
ignore all references to ASTC compressed textures.
Issues
(1) Which is the correct equation to use for converting
TEXTURE_BORDER_COLOR_OES when specified via SamplerParameteriv
or TexParameteriv?
RESOLVED: Early versions of GL 4.4 referenced both equations 2.1 and 2.2.
As per clarification in Bug 11185, the correct answer is equation 2.2.
(2) Does SamplerParmeter{if} set an error if called with
a non-scalar parameter?
RESOLVED: Yes. This should be analogous to TexParameteriv.
This error seems to be missing from GL 4.4. Filed bug 11186
to get this rectified.
(3) Should the second argument to GetTexParameterI* be <value> or <pname>?
RESOLVED: the GL specs call it <value>, but the headers call it <pname>.
The GetSamplerParameterI* version calls it <pname>, so we are doing the
same here for consistency. This was corrected in OpenGL ES 3.1.
Revision History
Rev. Date Author Changes
---- -------- --------- -------------------------------------------------
1 06/18/2014 dkoch Initial OES version based on EXT.
No functional changes.
