| Name |
| |
| ARB_internalformat_query |
| |
| Name Strings |
| |
| GL_ARB_internalformat_query |
| |
| Contact |
| |
| Jan-Harald Fredriksen (jan-harald.fredriksen 'at' arm.com) |
| Daniel Koch (daniel 'at' transgaming 'dot' com) |
| |
| Contributors |
| |
| Bruce Merry, ARM |
| Daniel Koch, Transgaming |
| Acorn Pooley, NVIDIA |
| Christophe Riccio, Imagination Technologies |
| |
| Notice |
| |
| Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at |
| http://www.khronos.org/registry/speccopyright.html |
| |
| Status |
| |
| Complete. Approved by the ARB on 2011/06/20. |
| Approved by the Khronos Promoters on 2011/07/29. |
| |
| Version |
| |
| Last Modified Date: June 13, 2011 |
| Revision: 7 |
| |
| Number |
| |
| ARB Extension #112 |
| |
| Dependencies |
| |
| OpenGL 3.0 or ARB_framebuffer_object is required. |
| |
| This extension is written against the OpenGL 4.1 (Core Profile) |
| Specification (July 25, 2010). |
| |
| ARB_texture_multisample affects the definition of this extension. |
| |
| Overview |
| |
| OpenGL 4.1 has a number of queries to indicate the maximum number of |
| samples available for different formats. These give a coarse-grained |
| query mechanism e.g. an implementation can expose different sample |
| counts for integer and floating-point formats, but not for different |
| floating-point formats. There is also no convenient way for the user |
| to determine the granularity of sample counts available, only the |
| maximum. |
| |
| This extension adds a query mechanism that allows the user to |
| determine which sample counts are available for a specific internal |
| format. |
| |
| IP Status |
| |
| No known IP claims. |
| |
| New Procedures and Functions |
| |
| void GetInternalformativ(enum target, enum internalformat, |
| enum pname, sizei bufSize, int *params); |
| |
| New Types |
| |
| None. |
| |
| New Tokens |
| |
| Accepted by the <target> parameter of GetInternalformativ: |
| |
| RENDERBUFFER |
| TEXTURE_2D_MULTISAMPLE |
| TEXTURE_2D_MULTISAMPLE_ARRAY |
| |
| Accepted by the <pname> parameter of GetInternalformativ: |
| |
| SAMPLES |
| NUM_SAMPLE_COUNTS 0x9380 |
| |
| Additions to Chapter 2 of the OpenGL 4.1 (Core Profile) Specification |
| (OpenGL Operation) |
| |
| None. |
| |
| Additions to Chapter 3 of the OpenGL 4.1 (Core Profile) Specification |
| (Rasterization) |
| |
| In section 3.8.6 (Multisample Textures), replace the bulleted |
| list of error conditions (for exceeding MAX_*_SAMPLES) and the |
| preceeding sentence with: |
| |
| "The error INVALID_OPERATION will be generated if <samples> is |
| greater than the maximum number of samples supported for this |
| <target> and <internalformat>, which can be determined by |
| calling GetInternalformativ with a <pname> of SAMPLES (see |
| section 6.X)." |
| |
| In the following paragraph, remove "or if samples is greater |
| than MAX_SAMPLES". |
| |
| Additions to Chapter 4 of the OpenGL 4.1 (Core Profile) Specification |
| (Per-Fragment Operations and the Frame Buffer) |
| |
| In section 4.4.2 (Attaching Images to Framebuffer Objects), under |
| the description of RenderbufferStorageMultisample: |
| |
| Replace |
| |
| "If either <width> or <height> is greater than the value of |
| MAX_RENDERBUFFER_SIZE, or if <samples> is greater than the value |
| of MAX_SAMPLES, then the error INVALID_VALUE is generated. If |
| <internalformat> is a signed or unsigned integer format and |
| <samples> is greater than the value of MAX_INTEGER_SAMPLES, then |
| the error INVALID_OPERATION is generated (see ``Required |
| Renderbuffer Formats'' below)." |
| |
| with |
| |
| "If either <width> or <height> is greater than the value of |
| MAX_RENDERBUFFER_SIZE then the error INVALID_VALUE is |
| generated. If <samples> is greater than the maximum number of |
| samples supported for <internalformat> then the error |
| INVALID_OPERATION is generated (see GetInternalformativ in |
| section 6.X)." |
| |
| Additions to Chapter 5 of the OpenGL 4.1 (Compatibility Profile) |
| Specification (Special Functions) |
| |
| Add GetInternalformativ to the list of commands not included in |
| display lists. |
| |
| Additions to Chapter 6 of the OpenGL 4.1 (Core Profile) Specification |
| (State and State Requests) |
| |
| Add a new section 6.1.X "Internalformat queries" |
| |
| Information about implementation-dependent support for internal |
| formats can be queried with the command |
| |
| void GetInternalformativ(enum target, enum internalformat, |
| enum pname, sizei bufSize, int *params); |
| |
| <internalformat> must be color-renderable, depth-renderable or |
| stencil-renderable (as defined in section 4.4.4). |
| |
| <target> indicates the usage of the <internalformat>, and must be |
| one of RENDERBUFFER, TEXTURE_2D_MULTISAMPLE, or |
| TEXTURE_2D_MULTISAMPLE_ARRAY, corresponding to usage as a |
| renderbuffer, 2D multisample texture, or 2D multisample array |
| texture. |
| |
| No more than <bufSize> integers will be written into <params>. If |
| more data are available, they will be ignored and no error will be |
| generated. |
| |
| <pname> indicates the information to query, and is one of the |
| following: |
| |
| - SAMPLES: The sample counts supported for this <format> and |
| <target> are written into <params>, in descending order. Only |
| positive values are returned. |
| - NUM_SAMPLE_COUNTS: The number of sample counts that would be |
| returned by querying SAMPLES is returned in <params>. |
| |
| Note that querying SAMPLES with a <bufSize> of 1 will return just |
| the maximum supported number of samples for this format. |
| |
| The maximum value in SAMPLES is guaranteed to be at least the lowest |
| of the following: |
| - The value of GetIntegerv(MAX_INTEGER_SAMPLES), if <internalformat> |
| is a signed or unsigned integer format. |
| - The value of GetIntegerv(MAX_DEPTH_TEXTURE_SAMPLES), if |
| <internalformat> is a depth/stencil-renderable format and <target> |
| is TEXTURE_2D_MULTISAMPLE or TEXTURE_2D_MULTISAMPLE_ARRAY. |
| - The value of GetIntegerv(MAX_COLOR_TEXTURE_SAMPLES), if |
| <internalformat> is a color-renderable format and <target> is |
| TEXTURE_2D_MULTISAMPLE or TEXTURE_2D_MULTISAMPLE_ARRAY. |
| - The value of GetIntegerv(MAX_SAMPLES). |
| |
| Additions to Appendix A of the OpenGL 4.1 (Core Profile) Specification |
| (Invariance) |
| |
| None. |
| |
| Additions to Appendix D of the OpenGL 4.1 (Core Profile) Specification |
| (Shared Objects and Multiple Contexts) |
| |
| None. |
| |
| GLX Protocol |
| |
| XXX - TODO. |
| |
| Dependencies on ARB_texture_multisample |
| |
| If OpenGL 3.2 or ARB_texture_multisample is not supported, then |
| TEXTURE_2D_MULTISAMPLE and TEXTURE_2D_MULTISAMPLE_ARRAY are not |
| supported <target> parameters to GetInternalformativ. |
| |
| Dependencies on OpenGL ES |
| |
| If implemented on OpenGL ES (together with an extension adding |
| RenderbufferStorageMultisample), then this extension behaves as |
| specified, except: |
| |
| - Ignore all references to multisample textures and display lists. |
| - Ignore all references to MAX_COLOR_TEXTURE_SAMPLES, |
| MAX_DEPTH_TEXTURE_SAMPLES, MAX_INTEGER_SAMPLES and MAX_SAMPLES. |
| |
| Errors |
| |
| If the <internalformat> parameter to GetInternalformativ is not |
| color-, depth- or stencil-renderable, then an INVALID_ENUM error is |
| generated. |
| |
| If the <target> parameter to GetInternalformativ is not one of |
| TEXTURE_2D_MULTISAMPLE, TEXTURE_2D_MULTISAMPLE_ARRAY or RENDERBUFFER |
| then an INVALID_ENUM error is generated. |
| |
| If the <pname> parameter to GetInternalformativ is not SAMPLES |
| or NUM_SAMPLE_COUNTS, then an INVALID_ENUM error is generated. |
| |
| If the <bufSize> parameter to GetInternalformativ is negative, |
| then an INVALID_VALUE error is generated. |
| |
| If the <samples> parameter to TexImage2DMultisample, |
| TexImage3DMultisample or RenderbufferStorageMultisample is greater |
| than the maximum number of samples supported for the target and |
| internalformat, an INVALID_OPERATION error is generated. |
| |
| An INVALID_VALUE error is no longer generated if the <samples> |
| argument to TexImage2DMultisample, TexImage3DMultisample or |
| RenderbufferStorageMultisample is greater than the value of |
| GetIntegerv(MAX_SAMPLES). |
| |
| New State |
| |
| None. |
| |
| New Implementation Dependent State |
| |
| Changes to table 6.52, p. 393 (Implementation Dependent Values) |
| |
| Minimum |
| Get Value Type Get Command Value Description Sec. |
| --------- ---- ----------- ------- ------------------------------------ ----- |
| MAX_DEPTH_TEXTURE_SAMPLES Z+ GetIntegerv 1 Maximum number of samples supported 6.1.X |
| for all depth/stencil formats in a |
| multisample texture |
| MAX_COLOR_TEXTURE_SAMPLES Z+ GetIntegerv 1 Maximum number of samples supported 6.1.X |
| for all color formats in a |
| multisample texture |
| MAX_INTEGER_SAMPLES Z+ GetIntegerv 1 Maximum number of samples supported 6.1.X |
| for all integer format multisample |
| buffers |
| |
| (only the description and section numbers change) |
| |
| Changes to table 6.54, p. 395 (Framebuffer Dependent Values) |
| |
| Minimum |
| Get Value Type Get Command Value Description Sec. |
| --------- ---- ----------- ------- ------------------------------------ ----- |
| MAX_SAMPLES Z+ GetIntegerv 4 Maximum number of samples supported 6.1.X |
| for all non-integer formats |
| |
| (only the description and section number change - note this query should |
| probably be in table 6.52 to start with) |
| |
| Add new table 6.X Internalformat-specific Implementation Dependent Values after 6.52 |
| |
| Minimum |
| Get Value Type Get Command Value Description Sec. |
| --------- ---- ----------- ------- ------------------------------------ ----- |
| SAMPLES 0*xZ+ GetInternalformativ fn1 Supported sample counts 6.X |
| NUM_SAMPLE_COUNTS Z+ GetInternalformativ 1 Number of supported sample counts 6.X |
| |
| fn1: see section 6.X. |
| |
| Sample Code |
| |
| To determine all the sample counts available for a specific |
| renderbuffer format: |
| |
| GLint *samples; |
| GLint samples_length, i; |
| |
| glGetInternalformativ(GL_RENDERBUFFER, format, |
| GL_NUM_SAMPLE_COUNTS, 1, &samples_length); |
| samples = malloc(samples_length * sizeof(GLint)); |
| glGetInternalformativ(GL_RENDERBUFFER, format, |
| GL_SAMPLES, samples_length, samples); |
| for (i = 0; i < samples_length; i++) |
| { |
| printf("Format %#x supports %d samples\n", samples[i]); |
| } |
| |
| To determine the maximum sample count available for a specific |
| renderbuffer format: |
| |
| GLint max_samples; |
| glGetInternalformativ(GL_RENDERBUFFER, format, |
| GL_SAMPLES, 1, &max_samples); |
| |
| Conformance Tests |
| |
| 1. Test each of the error conditions described in Errors. |
| |
| 2. For each format that is not color-, depth- or stencil-renderable |
| (if any), test that INVALID_ENUM is generated if passed to |
| GetInternalformativ (e.g. LUMINANCE_ALPHA). |
| |
| 3. Call GetInternalformativ for each <pname> in turn with a |
| <bufSize> of zero; check that <params> is not modified and that no |
| error results. |
| |
| 4. For each color-, depth- or stencil-renderable format and each |
| target: |
| 4.1. Query NUM_SAMPLE_COUNTS and verify that it is greater than |
| zero. |
| 4.2. Query SAMPLES, using a larger-than-necessary buffer, and |
| check that only NUM_SAMPLE_COUNTS values are written. |
| 4.3. Check that the values returned by SAMPLES are all positive |
| and strictly decreasing. |
| 4.4. Query MAX_SAMPLES and check that it matches the first value |
| returned by SAMPLES. |
| 4.5. Check that MAX_SAMPLES is at least the lower bound computed |
| from MAX_SAMPLES, MAX_INTEGER_SAMPLES, MAX_COLOR_TEXTURE_SAMPLES |
| and MAX_DEPTH_TEXTURE_SAMPLES. |
| 4.6. Check that MAX_SAMPLE_MASK_WORDS is at least |
| ceil(MAX_SAMPLES / 32). |
| |
| Issues |
| |
| 1) Should we have the MAX_SAMPLES query as well as the SAMPLES |
| query? It's syntactic sugar (since you can just take the largest |
| value in the SAMPLES array), but very convenient sugar since you |
| don't have to allocate a dynamically-sized array. It also simplifies |
| the specification. |
| |
| RESOLVED: no, we don't need it. Passing a <bufSize> of 1 when |
| querying SAMPLES gives the same effect. |
| |
| 2) Should we explicitly include 0 in the list of sample counts |
| (meaning "not multisampled")? It might allow one to indicate that certain |
| formats are flat-out unsupported with certain targets but supported with |
| others. |
| |
| RESOLVED: no, we would rather layer on a separate <pname> later. |
| |
| 3) For multisample textures, is a per-target query too fine-grained? |
| Should the <target> just be TEXTURE instead of |
| TEXTURE_2D_MULTISAMPLE[_ARRAY]? |
| |
| RESOLVED: Keep the per-target query as it may useful to distinguish |
| results for some future values of <pname>. |
| |
| 4) What should the new command be called? |
| |
| RESOLVED: GetInternalformativ |
| |
| GetInternalformativ is potentially confusing, but consistent with |
| GL precedent such as GetQueryiv (which returns information such as |
| the number of bits supported for a specific query target). |
| |
| 5) What should the query of the number of samples counts be called? |
| |
| RESOLVED: NUM_SAMPLE_COUNTS |
| |
| The original proposal was NUM_SAMPLES, which is consistent with |
| NUM_COMPRESSED_TEXTURE_FORMATS. However, it's confusing because what |
| is being queried is not the number of samples (whereas |
| NUM_COMPRESSED_TEXTURE_FORMATS is the number of compressed texture |
| formats). NUM_SAMPLE_COUNTS is also consistent with the |
| NUM_COMPRESSED_TEXTURE_FORMATS precedent and the description of this |
| value. |
| |
| Another proposal was SAMPLES_LENGTH, but this is misleading |
| because in OpenGL LENGTH is only used for string length. |
| |
| 6) What should GetIntegerv(MAX_INTEGER_SAMPLES) and similar queries |
| return (excluding MAX_SAMPLES - see next issue)? |
| |
| Discussion: there are (at least) two options: |
| |
| A. Querying MAX_INTEGER_SAMPLES returns a count that is guaranteed |
| to be supported for all integer formats, but some integer formats |
| may support more samples and the existing errors are relaxed to |
| allow this. |
| |
| B. Require that all integer formats support the same maximum number |
| of samples, and GetInternalformativ becomes an alternative |
| interface to the same set of limits. |
| |
| RESOLVED: option A. |
| |
| 7) What should GetIntegerv(MAX_SAMPLES) return? |
| |
| In OpenGL 4.1, MAX_SAMPLES serves two purposes. |
| A. An upper bound on the number of samples supported for any format. |
| This manifests in INVALID_VALUE errors when trying to use more than |
| this number. |
| B. A number of samples that is guaranteed to be supported for all |
| formats that don't fall into certain classes (such as integer |
| formats). |
| |
| Backwards compatibility would suggest that it should return option |
| B in future, although this leaves no way to determine the maximum |
| number of samples supported for any format unless a new query is |
| introduced. |
| |
| RESOLVED: option B. |
| |
| 8) Does this extension make the MAX_SAMPLES query unnecessary? |
| |
| RESOLVED: MAX_SAMPLES will need to be retained in API versions where |
| it already exists (for backwards compatibilities), but there is no |
| need to add it as this query provides more accurate information and |
| it is expected that shipping hardware will support different numbers |
| of samples for different formats. |
| |
| 9) Can we query additional properties supported for an internal format |
| in addition to multisample-related information with this API? |
| |
| RESOLVED: DEFERRED. Yes this API is suitable for that, but the |
| specification is left for a layered extension. |
| |
| Other possible <pnames> include: |
| MAX_WIDTH |
| - maximum width of object |
| MAX_HEIGHT |
| - maximum height of object |
| MAX_DEPTH |
| - maximum depth/# of layers of object |
| MAX_COMBINED_SIZE |
| - maximum size of object (w*h*d) (due to implementation-specific |
| limitations) |
| FRAMEBUFFER_RENDERABLE |
| - can be rendered to via FBO attachment |
| FRAMEBUFFER_RENDERABLE_BLEND |
| - can be rendered to via FBO attachment when blending is enabled |
| MIPMAPS |
| - more than one mipmap can be supported |
| GENERATE_MIPMAPS |
| - is generate mipmaps supported |
| READPIXEL |
| - framebuffers with this internal format can be read directly with |
| an appropriate format/type by ReadPixels |
| FILTER_LINEAR |
| - can the MIN/MAG filter be set to LINEAR values? Are filters other |
| than NEAREST supported? |
| SRGB_READ |
| - texture reads from this internalformat occur in SRGB colorspace |
| SRGB_WRITE |
| - framebuffers with this internalformat can be rendered to with |
| FRAMEBUFFER_SRGB enabled |
| SRGB_DECODE |
| - textures of this format support toggling TEXTURE_SRGB_DECODE |
| (ie EXT_texture_sRGB_decode) |
| VERTEX_TEXTURE |
| - textures with this internalformat can be sampled from vertex shaders |
| TESS_CONTROL_TEXTURE |
| - textures with this internalformat can be sampled from tessellation |
| control shaders |
| TESS_EVALUATION_TEXTURE |
| - textures with this internalformat can be sampled from tessellation |
| evaluation shaders |
| GEOMETRY_TEXTURE |
| - textures with this internalformat can be sampled from geometry shaders |
| FRAGMENT_TEXTURE |
| - textures with this internalformat can be sampled from fragment shaders |
| TEXTURE_SHADOW |
| - textures with this internalformat support shadow samplers |
| TEXTURE_GATHER |
| - textures with this internalformat support texture gather operations |
| TEXTURE_GATHER_SHADOW |
| - textures with this internalformat support texture gather operations |
| with shadow samplers |
| SHADER_IMAGE_LOAD |
| - textures with this internalformat support image load operations |
| from shaders |
| SHADER_IMAGE_STORE |
| - textures with this internalformat support image store operations |
| from shaders |
| SHADER_IMAGE_ATOMIC |
| - textures with this internalformat support atomic memory operations |
| from shaders |
| FORMAT_SUPPORTED |
| - the requested internal format is known and supported for at least |
| some subset of the possible operations |
| ACTUAL_INTERNALFORMAT |
| - the actual internalformat used by the implementation when the |
| specified internalformat is requested |
| PERFORMANCE_HINT |
| - an indication that this format will or may operate at reduced |
| performance in some cases (should this be a bitfield, array, |
| or a specific bit on each of the other queries?) |
| |
| Possible values for some of the above pnames: |
| - HARDWARE (or SUPPORTED), SOFTWARE (or CAVEAT), UNSUPPORTED. |
| |
| Additional Values for <target> that would be valid for |
| TEXTURE_1D |
| TEXTURE_1D_ARRAY |
| TEXTURE_2D |
| TEXTURE_2D_ARRAY |
| TEXTURE_3D |
| TEXTURE_CUBE_MAP |
| TEXTURE_CUBE_MAP_ARRAY |
| TEXTURE_RECTANGLE |
| TEXTURE_BUFFER |
| Could also consider meta targets such as: |
| ALL |
| ANY |
| TEXTURE |
| |
| |
| 10) Is the <target> parameter required? If so, should it be the first or |
| second parameter? |
| |
| RESOLVED: |
| a) Yes. It is possible that in some implementations and for some of the possible |
| uses of this query, that the results will depend on the texture target. |
| b) First parameter. All other entry points that take a <target> have it as the |
| first parameter. |
| |
| Revision History |
| |
| Revision 7, 2011/06/13 dgkoch |
| - recast as ARB extension |
| |
| Revision 6, 2011/05/19 dgkoch |
| - resolved issue 3, 9 per F2F. |
| |
| Revision 5, 2011/05/16 dgkoch |
| - resolved issue 10 per F2F. Keep target; as the first parameter. |
| - fix extension name |
| - updates to Issue 9 |
| |
| Revision 4, 2011/05/11 dgkoch |
| - also fix the formal paramter in the New Functions area |
| - updates to issue 9, added issue 10 |
| |
| Revision 3, 2011/05/05 dgkoch |
| - rename the formal parameter from 'format' to 'internalformat' |
| to match the spec body. |
| - changed SAMPLES_LENGTH to NUM_SAMPLE_COUNTS |
| - added issue 9 |
| |
| Revision 2, 2011/04/21 bmerry |
| - Fix typo InternalFormat -> Internalformat |
| - Removed per-format MAX_SAMPLES query |
| - Marked issues 1, 2, and 4-7 as resolved |
| |
| Revision 1, 2011/04/13 bmerry |
| - First draft. |