Discrepancy between `glGetInternalformat` documentation and `ARB_internalformat_query2` one

[illwieckz]

Hi! A discrepancy in OpenGL documentation was discovered:

The glGetInternalformat reference page says that it should return either GL_TRUE or GL_FALSE when queried for GL_FRAMEBUFFER_BLEND, but the ARB_internalformat_query2 extension page says it should return either GL_FULL_SUPPORT, GL_CAVEAT_SUPPORT, or GL_NONE.

If pname is GL_FRAMEBUFFER_BLEND, params is set to GL_TRUE to indicate that the internal format is supported for blending operations when attached to a framebuffer, and to GL_FALSE otherwise.
-- https://registry.khronos.org/OpenGL-Refpages/gl4/html/glGetInternalformat.xhtml

FRAMEBUFFER_BLEND: The support for rendering to the resource via framebuffer attachment when blending is enabled is returned in params. Possible values returned are FULL_SUPPORT, CAVEAT_SUPPORT, or NONE. If the resource is unsupported, NONE is returned.
-- https://registry.khronos.org/OpenGL/extensions/ARB/ARB_internalformat_query2.txt

While GL_FALSE and GL_NONE are equal (0), GL_FULL_SUPPORT (33463) and GL_TRUE (1) are not.

[illwieckz]

It was discovered while trying to implement properly the FRAMEBUFFER_BLEND query on Mesa side:

• https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/30612

Previously Mesa was always returning GL_FULL_SUPPORT even if the feature was not supported. If the expected values are either GL_TRUE or GL_FALSE it may be handy to detect a buggy Mesa by getting GL_FULL_SUPPORT, but if the expected values are either GL_FULL_SUPPORT, GL_CAVEAT_SUPPORT, or GL_NONE, the mess may be more annoying.

[illwieckz]

In OpenGL 4.3 Core specification, we can read on section “22.3. INTERNAL FORMAT QUERIES”, page 496 (517):

FRAMEBUFFER_BLEND: The support for rendering to the resource via frame-
buffer attachment when blending is enabled is returned in params. Possible
values returned are FULL_SUPPORT, CAVEAT_SUPPORT, or NONE. If the re-
source is unsupported, NONE is returned.
-- https://registry.khronos.org/OpenGL/specs/gl/glspec43.core.pdf#page=517

This is basically a copy-paste of the ARB_internalformat_query2 extension document (or the other way around).

[illwieckz]

I still don't get the meaning of CAVEAT_SUPPORT in such situation.

Let's take this query as an example:

glGetInternalformati64v( GL_TEXTURE_2D, GL_RGBA16, GL_FRAMEBUFFER_BLEND, 1, &param );

Should the driver (first proposition):

• return GL_FULL_SUPPORT when RGBA16 framebuffers are supported and blending them are both supported,
• or return GL_NONE if either RGBA16 framebuffers are not supported or blending them is not?

Or should the driver (second proposition):

• return GL_FULL_SUPPORT when RGBA16 framebuffers are supported and blending them are both supported,
• or return GL_CAVEAT_SUPPORT when RGBA16 framebuffers are supported but blending them is not,
• or return GL_NONE when both RGBA16 framebuffers are not supported or blending them is not?

If the first proposition is the correct one, that would mean GL_CAVEAT_SUPPORT has no meaning and no usage when querying FRAMEBUFFER_BLEND, and then the usage of a three-state return would not make sense, be over-engineered and be confusing compared to what a boolean provides, and there would be no reason to not use GL_TRUE/GL_FALSE instead.

[illwieckz]

The OpenGL wiki page for glGetInternalformat says the same as the OpenGL 4.3 Core specification and the ARB_internalformat_query2 document (three-state return):

GL_FRAMEBUFFER_BLEND
GL_FULL_SUPPORT, GL_CAVEAT_SUPPORT or GL_NONE to indicate full support, limited support or no support for blending operations with the internal format when attached to a framebuffer.
-- https://www.khronos.org/opengl/wiki/GLAPI/glGetInternalformat

[tpalli]

Meaning of CAVEAT_SUPPORT is explained in the GL specification. It means that there is support but it comes with some extra cost:

CAVEAT_SUPPORT: the requested operation is supported by the implemen-
tation, but there may be some implementation-specific caveats that make
support less than optimal. For example using the feature may result in re-
duced performance (relative to other formats or features), such as software
rendering or other mechanisms of emulating the desired feature.

[zmike]

@oddhack please change the text in the refpage from

If pname is GL_FRAMEBUFFER_BLEND, params is set to GL_TRUE to indicate that the internal format is supported for blending operations when attached to a framebuffer, and to GL_FALSE otherwise.

to

If pname is GL_FRAMEBUFFER_BLEND, then params is set to one of GL_FULL_SUPPORT, GL_CAVEAT_SUPPORT or GL_NONE to indicate that framebuffer attachments with that internal format either support blending operations with no restrictions, support blending operations with some restrictions or do not support blending operations at all.