xref: /third_party/openGLES/extensions/ARB/ARB_multi_bind.txt

Name

    ARB_multi_bind

Name Strings

    GL_ARB_multi_bind

Contact

    Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com)

Contributors

    Jeff Bolz, NVIDIA
    Frank Chen, Qualcomm
    Piers Daniell, NVIDIA
    Daniel Koch, NVIDIA
    Jon Leech

Notice

    Copyright (c) 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 on June 3, 2013.
    Ratified by the Khronos Board of Promoters on July 19, 2013.

Version

    Last Modified Date:         May 30, 2013
    Revision:                   10

Number

    ARB Extension #147

Dependencies

    This extension is written against the OpenGL 4.3 (Compatibility Profile)
    Specification, dated August 6, 2012.

    OpenGL 3.0 is required.

    This extension interacts with OpenGL 3.3 and ARB_sampler_objects.

    This extension interacts with OpenGL 4.3 and ARB_vertex_attrib_binding.

Overview

    This extension provides a new set of commands allowing applications to
    bind or unbind a set of objects in a single call, instead of requiring a
    separate call for each bind or unbind operation.  Using a single command
    allows OpenGL implementations to amortize function call, name space
    lookup, and potential locking overhead over multiple bind or unbind
    operations.  The rendering loops of graphics applications frequently
    switch between different states, binding different sets of resources,
    including texture objects, sampler objects, textures for image loads and
    stores, uniform buffers, and vertex buffers; this extension provides
    "multi-bind" entry points for all of these object types.

    Each command in this extension includes a <first> and <count> parameter,
    specifying a continguous range of binding points to update, as well as an
    array of <count> object names specifying the objects to bind.  Unlike
    single bind commands, multi-bind commands can be used only to bind or
    unbind existing objects.  Passing a previously unused object name
    (generated or not) results in an error and does not create a new object.
    For binding points with associated data (e.g., ranges of a buffer),
    separate arrays are used to pass the associated data for each binding
    point.  Passing zero values in the array of object names removes the
    object bound to the current bounding point.  Additionally, if NULL is
    passed as the array of objects, objects bound to the entire range of
    binding points are unbound, as though the caller passed an array of
    zeroes.

New Procedures and Functions

    void BindBuffersBase(enum target, uint first, sizei count, 
                         const uint *buffers);

    void BindBuffersRange(enum target, uint first, sizei count, 
                          const uint *buffers, const intptr *offsets,
                          const sizeiptr *sizes);

    void BindTextures(uint first, sizei count, const uint *textures);

    void BindSamplers(uint first, sizei count, const uint *samplers);

    void BindImageTextures(uint first, sizei count, const uint *textures);

    void BindVertexBuffers(uint first, sizei count, const uint *buffers,
                           const intptr *offsets, const sizei *strides);

New Tokens

    None.

Modifications to the OpenGL 4.3 (Compatibility Profile) Specification

    Modify Section 2.3.1, Errors, p. 15

    (modify third paragraph, p. 16, adding "unless otherwise noted"
     qualification to the general rule that commands producing errors have no
     side effects)

    Table 2.3 summarizes ...  if an OUT_OF_MEMORY error has occurred.  In
    other cases, there are no side effects unless otherwise noted; the command
    which generates the error is ignored so that it has no effect on GL state
    or framebuffer contents. ...


    Modify Section 6.1.1, Binding Buffer Objects To Indexed Targets, p. 55

    (insert immediately after the "Errors" block at the end of the section,
    p. 56)

    The commands

      void BindBuffersBase(enum target, uint first, sizei count, 
                           const uint *buffers);

      void BindBuffersRange(enum target, uint first, sizei count, 
                            const uint *buffers, const intptr *offsets,
                            const sizeiptr *sizes);

    bind <count> existing buffer objects to bindings numbered <first> through
    <first>+<count>-1 in the array of buffer binding points corresponding to
    <target>.  If <buffers> is not NULL, it specifies an array of <count>
    values, each of which must be zero or the name of an existing buffer
    object.  For BindBuffersRange, <offsets> and <sizes> specify arrays of
    <count> values indicating the range of each buffer to bind.  If <buffers>
    is NULL, all bindings from <first> through <first>+<count>-1 are reset
    to their unbound (zero) state. In this case, the offsets and sizes
    associated with the binding points are set to default values, ignoring
    <offsets> and <sizes>.

    BindBuffersBase is equivalent to:

      for (i = 0; i < count; i++) {
        if (buffers == NULL) {
          glBindBufferBase(target, first + i, 0);
        } else {
          glBindBufferBase(target, first + i, buffers[i]);
        }
      }

    except that the single general buffer binding corresponding to <target>
    is unmodified, and that buffers will not be created if they do not
    exist.

    BindBuffersRange is equivalent to:

      for (i = 0; i < count; i++) {
        if (buffers == NULL) {
          glBindBufferRange(target, first + i, 0, 0, 0);
        } else {
          glBindBufferRange(target, first + i, buffers[i], offsets[i], 
                            sizes[i]);
        }
      }

    except that the single general buffer binding corresponding to <target>
    is unmodified, and that buffers will not be created if they do not
    exist.

    The values specified in <buffers>, <offsets>, and <sizes> will be checked
    separately for each binding point.  When values for a specific binding
    point are invalid, the state for that binding point will be unchanged and
    an error will be generated.  However, state for other binding points will
    still be changed if their corresponding values are valid.

    Errors

      An INVALID_ENUM error is generated if <target> is not one of the targets
      listed above.

      An INVALID_OPERATION error is generated if <first> + <count> is greater
      than the number of target-specific indexed binding points, as described
      in section 6.7.1.

      An INVALID_OPERATION error is generated if any value in <buffers> is not
      zero or the name of an existing buffer object (per binding).

      An INVALID_VALUE error is generated by BindBuffersRange if any value in
      <offsets> is less than zero (per binding).

      An INVALID_VALUE error is generated by BindBuffersRange if any value in
      <sizes> is less than or equal to zero (per binding).

      An INVALID_VALUE error is generated by BindBuffersRange if any pair of
      values in <offsets> and <sizes> does not respectively satisfy the
      constraints described for those parameters for the specified target, as
      described in section 6.7.1 (per binding).


    Modify Section 8.1, Texture Objects (p. 155)

    (insert after errors section, p. 156)

    The command

      void BindTextures(uint first, sizei count, const uint *textures);

    binds <count> existing texture objects to texture image units numbered
    <first> through <first>+<count>-1.  If <textures> is not NULL, it
    specifies an array of <count> values, each of which must be zero or the
    name of an existing texture object.  When an entry in <textures> is the
    name of an existing texture object, that object is bound to corresponding
    texture unit for the target specified when the texture object was created.
    When an entry in <textures> is zero, each of the targets enumerated at the
    beginning of this section is reset to its default texture for the
    corresponding texture image unit.  If <textures> is NULL, each target of
    each affected texture image unit from <first> through <first>+<count>-1 is
    reset to its default texture.

    BindTextures is equivalent to

      for (i = 0; i < count; i++) {
        uint texture;
        if (textures == NULL) { 
          texture = 0;
        } else {
          texture = textures[i];
        }
        ActiveTexture(TEXTURE0 + first + i);
        if (texture != 0) {
          enum target = /* target of texture object textures[i] */;
          BindTexture(target, textures[i]);
        } else {
          for (target in all supported targets) {
            BindTexture(target, 0);
          }
        }
      }

    except that the active texture selector retains its original value upon
    completion of the command, and that textures will not be created if they
    do not exist.


    The values specified in <textures> will be checked separately for each
    texture image unit.  When a value for a specific texture image unit is
    invalid, the state for that texture image unit will be unchanged and an
    error will be generated.  However, state for other texture image units
    will still be changed if their corresponding values are valid.

    Errors

      An INVALID_OPERATION error is generated if <first> + <count> is greater
      than the number of texture image units supported by the implementation.

      An INVALID_OPERATION error is generated if any value in <textures> is
      not zero or the name of an existing texture object (per binding).


    Modify Section 8.2, Sampler Objects (p. 158)

    (insert after errors section, p. 159)

    The command

      void BindSamplers(uint first, sizei count, const uint *samplers);

    binds <count> existing sampler objects to texture image units numbered
    <first> through <first>+<count>-1.  If <samplers> is not NULL, it
    specifies an array of <count> values, each of which must be zero or the
    name of an existing sampler object.  If <samplers> is NULL, each affected
    texture image unit from <first> through <first>+<count>-1 will be reset to
    have no bound sampler object.

    BindSamplers is equivalent to

      for (i = 0; i < count; i++) {
        if (samplers == NULL) {
          glBindSampler(first + i, 0);
        } else {
          glBindSampler(first + i, samplers[i]);
        }
      }

    The values specified in <samplers> will be checked separately for each
    texture image unit.  When a value for a specific texture image unit is
    invalid, the state for that texture image unit will be unchanged and an
    error will be generated.  However, state for other texture image units
    will still be changed if their corresponding values are valid.

    Errors

      An INVALID_OPERATION error is generated if <first> + <count> is greater
      than the number of texture image units supported by the implementation.

      An INVALID_OPERATION error is generated if any value in <samplers> is
      not zero or the name of an existing sampler object (per binding).


    Modify Section 8.25, Texture Image Loads and Stores, p. 281

    (insert before the next-to-last paragraph, p. 282, "When a shader
     accesses...")

    The command

      void BindImageTextures(uint first, sizei count, const uint *textures);

    binds <count> existing texture objects to image units numbered <first>
    through <first>+<count>-1.  If <textures> is not NULL, it specifies an
    array of <count> values, each of which must be zero or the name of an
    existing texture object.  If <textures> is NULL, each affected image unit
    from <first> through <first>+<count>-1 will be reset to have no bound
    texture object.

    When binding a non-zero texture object to an image unit, the image unit
    <level>, <layered>, <layer>, and <access> parameters are set to zero,
    TRUE, zero, and READ_WRITE, respectively.  The image unit <format>
    parameter is taken from the internal format of the texture image at level
    zero of the texture object identified by <textures>.  For cube map
    textures, the internal format of the TEXTURE_CUBE_MAP_POSITIVE_X image of
    level zero is used.  For multisample, multisample array, buffer, and
    rectangle textures, the internal format of the single texture level is
    used.

    When unbinding a texture object from an image unit, the image unit
    parameters <level>, <layered>, <layer>, and <format> will be reset to
    their default values of zero, FALSE, 0, and R8, respectively.

    BindImageTextures is equivalent to

      for (i = 0; i < count; i++) {
        if (textures == NULL || textures[i] = 0) {
          glBindImageTexture(first + i, 0, 0, FALSE, 0, READ_ONLY, R8);
        } else {
          glBindImageTexture(first + i, textures[i], 0, TRUE, 0, READ_WRITE,
                             lookupInternalFormat(textures[i]));
        }
      }

    where lookupInternalFormat returns the internal format of the specified
    texture object.

    The values specified in <textures> will be checked separately for each
    image unit.  When a value for a specific image unit is invalid, the state
    for that image unit will be unchanged and an error will be generated.
    However, state for other image units will still be changed if their
    corresponding values are valid.

    Errors

      An INVALID_OPERATION error is generated if <first> + <count> is greater
      than the number of image units supported by the implementation.

      An INVALID_OPERATION error is generated if any value in <textures> is
      not zero or the name of an existing texture object (per binding).

      An INVALID_OPERATION error is generated if the internal format of the
      level zero texture image of any texture in <textures> is not found in
      table 8.33 (per binding).

      An INVALID_OPERATION error is generated if the width, height, or depth
      of the level zero texture image of any texture in <textures> is zero
      (per binding).


    Modify Section 10.3.1, Specifying Arrays For Generic Attributes, p. 340

    (insert after first errors section, p. 343)

    The command

      void BindVertexBuffers(uint first, sizei count, const uint *buffers,
                             const intptr *offsets, const sizei *strides);

    binds <count> existing buffer objects to vertex buffer binding points
    numbered <first> through <first>+<count>-1.  If <buffers> is not NULL, it
    specifies an array of <count> values, each of which must be zero or the
    name of an existing buffer object.  <offsets> and <strides> specify arrays
    of <count> values indicating the offset of the first element and stride
    between elements in each buffer, respectively.  If <buffers> is NULL, each
    affected vertex buffer binding point from <first> through
    <first>+<count>-1 will be reset to have no bound buffer object.  In this
    case, the offsets and strides associated with the binding points are set
    to default values, ignoring <offsets> and <strides>.

    BindVertexBuffers is equivalent to

      for (i = 0; i < count; i++) {
        if (buffers == NULL) {
          glBindVertexBuffer(first + i, 0, 0, 16);
        } else {
          glBindVertexBuffer(first + i, buffers[i], offsets[i], strides[i]);
        }
      }

    except that buffers will not be created if they do not exist.

    The values specified in <buffers>, <offsets>, and <strides> will be
    checked separately for each vertex buffer binding point.  When a value for
    a specific binding point is invalid, the state for that binding point will
    be unchanged and an error will be generated.  However, state for other
    binding points will still be changed if their corresponding values are
    valid.

    Errors

      An INVALID_OPERATION error is generated if <first> + <count> is greater
      than the value of MAX_VERTEX_ATTRIB_BINDINGS.

      An INVALID_OPERATION error is generated if any value in <buffers> is not
      zero or the name of an existing buffer object (per binding).

      An INVALID_VALUE error is generated if any value in <offsets> or
      <strides> is negative (per binding).


    Modify Section 21.4.1, Commands Not Usable in Display Lists, p. 618

    (add a new section below "Debug output", p. 619)

    Multi-object binds:  BindBuffersBase, BindBuffersRange, BindTextures,
    BindSamplers, BindImageTextures, BindVertexBuffers


Additions to the AGL/EGL/GLX/WGL Specifications

    None

GLX Protocol

    TBD

Dependencies on OpenGL 3.3 and ARB_sampler_objects

    If neither OpenGL 3.3 nor ARB_sampler_objects is supported, references to
    BindSamplers should be removed.

Dependencies on OpenGL 4.3 and ARB_vertex_attrib_binding

    If neither OpenGL 4.3 nor ARB_vertex_attrib_binding is supported,
    references to BindVertexBuffers should be removed.

Errors

    An INVALID_ENUM error is generated by BindBuffersBase or BindBuffersRange
    if <target> is not one of the indexed targets for buffer bindings.

    An INVALID_OPERATION error is generated by BindBuffersBase or
    BindBuffersRange if <first> + <count> is greater than the number of
    target-specific indexed binding points, as described in section 6.7.1.

    An INVALID_OPERATION error is generated by BindBuffersBase or
    BindBuffersRange if any value in <buffers> is not zero or the name of an
    existing buffer object (per binding).

    An INVALID_VALUE error is generated by BindBuffersRange if any value in
    <offsets> is less than zero (per binding).

    An INVALID_VALUE error is generated by BindBuffersRange if any value in
    <sizes> is less than or equal to zero (per binding).

    An INVALID_VALUE error is generated by BindBuffersRange if any pair of
    values in <offsets> and <sizes> do not respectively satisfy the
    constraints described for those parameters for the specified target, as
    described in section 6.7.1 (per binding).

    An INVALID_OPERATION error is generated by BindTextures if <first> +
    <count> is greater than the number of texture image units supported by the
    implementation.

    An INVALID_OPERATION error is generated by BindTextures if any value in
    <textures> is not zero or the name of an existing texture object (per
    binding).

    An INVALID_OPERATION error is generated by BindSamplers if <first> +
    <count> is greater than the number of texture image units supported by the
    implementation.

    An INVALID_OPERATION error is generated by BindSamplers if any value in
    <samplers> is not zero or the name of an existing texture object (per
    binding).

    An INVALID_OPERATION error is generated by BindImageTextures if <first> +
    <count> is greater than the number of image units supported by the
    implementation.

    An INVALID_OPERATION error is generated by BindImageTextures if any value
    in <textures> is not zero or the name of an existing texture object (per
    binding).

    An INVALID_OPERATION error is generated by BindImageTextures if the
    internal format of the level zero texture image of any texture in
    <textures> is not found in table 8.33 (per binding).

    An INVALID_OPERATION error is generated by BindImageTextures if the width,
    height, or depth of the level zero texture image of any texture in
    <textures> is zero (per binding).

    An INVALID_OPERATION error is generated by BindVertexBuffers if <first> +
    <count> is greater than the value of MAX_VERTEX_ATTRIB_BINDINGS.

    An INVALID_OPERATION error is generated by BindVertexBuffers if any value
    in <buffers> is not zero or the name of an existing texture object (per
    binding).

    An INVALID_VALUE error is generated by BindVertexBuffers if any value in
    <offsets> or <strides> is negative (per binding).

New State

    None.

New Implementation Dependent State

    None.

Issues

    (1) Regular binding commands such as BindBuffer or BindTexture can be used
        either to bind an existing object or to create and bind a new object.
        Should the multi-bind commands behave similarly?

      RESOLVED:  No.  Multi-Bind commands will only support binding existing
      objects.  They will generate an error if any of the provided objects
      doesn't already exist.

      This extension is intended to provide efficient APIs allowing
      applications to bind multiple objects for rendering in a single command.
      Implementations of these commands are intended to bind the objects to
      consecutive binding points in a loop amortizing function call, name
      space lookup, locking, and other overhead over <N> objects.  Not
      supporting bind-to-create reduces the number of cases that this loop
      needs to handle.

      Even if bind-to-create were supported, it probably wouldn't be very
      useful.  When bind-to-create is used in current single-bind APIs, the
      binding serves two purposes -- to create the object and to bind it for
      use by subsequent "update" APIs defining the state of the new object.
      In a multi-Bind API, it wouldn't be possible to bind more than one of
      the <N> objects for update.

      Additionally, if BindTexture is used to create a texture object, the
      texture type is established based on the <target> parameter (e.g.,
      TEXTURE_2D).  The multi-Bind API for textures doesn't include <target>
      parameters, so we wouldn't know what type of texture to create.

    (2) Should we provide a command binding multiple texture objects of
        different targets (e.g., TEXTURE_2D and TEXTURE_3D) in a single call?
        For example, should you be able to bind three 2D textures to the
        TEXTURE_2D target of image units 1, 2, and 3, as well as binding two
        3D textures to the TEXTURE_3D target of texture image units 0 and 4?

      RESOLVED:  Yes.  The BindTextures() command does not take <target>
      enums.  Instead, the target used for each texture image unit comes from
      the target used when the texture object was created.

    (3) Should we support unbinding objects in a multi-bind command?  If so,
        how does this work for texture objects, where each texture image unit
        has multiple binding points (targets)?

      RESOLVED:  Yes, applications can unbind objects by passing zero in the
      array of object names.  For textures, passing zero will unbind textures
      from all texture targets.

    (4) Should we provide a simple way to unbind objects from a collection of
        contiguous binding points?

      RESOLVED:  Yes, passing a NULL pointer instead of an array of object
      names does an unbind for all binding points.  Basically, it's treated
      like an array of zeroes.

    (5) Should we support multiple bindings of buffer objects using both the
        "BindBufferBase" and the "BindBufferRange" styles?  If so, what name
        should we use for these APIs?

      RESOLVED:  Yes.  BindBuffersBase() is equivalent to a loop repeatedly
      calling BindBufferBase(); BindBuffersRange() is equivalent to a loop
      repeatedly calling BindBufferRange().

      The name choice for the "plural" forms of BindBufferBase and
      BindBufferRange was tricky.  "BindBufferRanges" would have been a fine
      choice for BindBufferRange, but using "BindBufferBases" would have been
      strange since "BindBufferBase" means "bind a buffer from the base of its
      storage (offset zero)".  We considered "BindBuffers" as the plural for
      "BindBufferBase", but decided to use "BindBuffers{Base,Range}".

    (6) If we support multiple bindings using the BindBufferRange style, how
        should the application specify the ranges?

      RESOLVED:  Applications will pass separate arrays of offsets and sizes.

      Alternate options included:

        * a single array where entry 2<N> specifies the offset for binding <N>
          and entry 2<N>+1 specifies the size for binding <N>;

        * defining a new structure type including an offset and a size, and
          accepting an array of <N> structures

    (7) Should we create a "multi-bind" command for specifying vertex buffer
        bindings (those specified via BindVertexBuffer)?

      RESOLVED:  Yes.

    (8) If we add a "multi-bind" command for specifying vertex buffer
        bindings, should we also create a similar command for specifying
        multiple vertex formats (VertexAttrib*Format) in a single call?

      RESOLVED:  No.  The design of ARB_vertex_attrib_binding separated
      vertex buffer bindings from vertex formats, expecting that many
      applications will change bindings frequently but change formats
      relatively infrequently.  While we could create a command specifying
      multiple formats at once, but it would require us to turn several format
      parameters (<size>, <type>, <normalized>, <relativeoffset>) into arrays.

      Additionally, mutable vertex array objects can already be used to make a
      wholesale change of formats and bindings.  An application using a small
      number of formats with a large number of bindings could create a
      separate VAO for each format, and then change bindings with the
      "multi-bind" command.

    (9) Should we provide a command to specify multiple image unit bindings in
        a single command?

      RESOLVED:  Yes.  We decided to support this for completeness, though the
      required number of image units is relatively small (8).

    (10) Should binding an array of buffer objects via BindBuffersBase or
         BindBuffersRange update the generic (non-indexed) binding points for
         <target>?

      RESOLVED:  No.

      In unextended OpenGL 4.3, targets like UNIFORM_BUFFER include both an
      array of indexed bindings used for shader execution as well as a generic
      "non-indexed" binding point that can be used for commands such as
      BufferSubData.  Calling BindBufferBase or BindBufferRange updates two
      binding points -- binding <index> in the array of indexed bindings as
      well as the generic binding point.  Updating both binding points allows
      applications to bind a buffer for manipulation and update in a single
      command.

      For BindBuffersBase and BindBuffersRange, the caller specifies <count>
      separate buffers.  We have specified these commands not to update the
      generic binding point.  Even if we were to update the generic binding
      point, we'd have to pick one arbitrarily.

    (11) Typically, OpenGL specifies that if an error is generated by a
         command, that command has no effect.  This is somewhat unfortunate
         for multi-bind commands, because it would require a first pass to
         scan the entire list of bound objects for errors and then a second
         pass to actually perform the bindings.  Should we have different
         error semantics?

      RESOLVED:  Yes.  In this specification, when the parameters for one of
      the <count> binding points are invalid, that binding point is not
      updated and an error will be generated.  However, other binding points
      in the same command will be updated if their parameters are valid and no
      other error occurs.

    (12) What error should be generated if the <first> and <count> parameters
         specified in multi-bind commands specify a range beyond
         implementation-dependent limits?

      RESOLVED:  INVALID_OPERATION is typically generated when the
      combination of two values is illegal.  INVALID_VALUE would also be
      defensible.

    (13) How are the <offsets> and <sizes> parameters of BindBuffersRange used
         if <buffers> is NULL?

      RESOLVED:  We specify that these parameters are ignored when buffers
      is NULL, so that applications can unbind a range of buffers with:

        BindBuffersRange(target, 0, 8, NULL, NULL, NULL);

    (14) Should we provide a "multi-bind" API to attach multiple textures to
         the color attachments of a framebuffer object?  Should we add an API
         populating all attachments at once?

      RESOLVED:  No.  We could consider an API like:

        void FramebufferColorTextures(enum target, uint first, sizei count,
                                      const uint *textures, 
                                      const uint *levels);

      One might omit the <levels> parameter, since level 0 is used most
      frequently, and non-zero levels could still be handled by creating
      spearate views via ARB_texture_view.  If we wanted to be able to specify
      the full set of attachments at once, we could have:

        void FramebufferTextures(enum target, sizei count,
                                 const uint *colorAttachments,
                                 const uint depthAttachment,
                                 const uint stencilAttachment);

      This API effectively omits the <first> argument and always starts at
      zero.  The "all attachments" API could be handled in OpenGL today by
      using separate framebuffer objects for each attachment combination.
      However, for applications that work with various combinations of
      attachments but don't already have a notion of "attachment sets" to map
      to framebuffer objects, caching different attachment combinations is
      somewhat unwieldy.

    (15) Should we provide a multi-bind API that binds pairs of textures and
    samplers to a set of consecutive texture image units?

      RESOLVED:  No.  We could provide a command such as:

        void BindTexturesSamplers(uint first, sizei count,
                                  const uint *textures, 
                                  const uint *samplers);

      that would be roughly equivalent to:

        BindTextures(first, count, textures);
        BindSamplers(first, count, samplers);

      If we did this, we'd have to decide how it would interact with the error
      semantics in issue (11).  If we have an error generated because of an
      invalid texture for a given unit, would the sampler state for that unit
      still be updated if the sampler provided were valid?  Since we chose not
      to support this feature, we don't need to address this question.

    (16) When binding a non-zero texture to a texture image unit, should
         BindTextures implicitly unbind the textures bound to all other
         targets of the unit?

      RESOLVED:  No.

      This approach was considered to behave similarly to the proposed
      behavior for binding zero in a multi-bind API, where it unbinds any
      bound texture for all targets.  Applications using BindTextures
      exclusively would never have more than one texture bound to the targets
      of a texture image unit.  A driver implementation might optimize for
      this behavior by having a single "primary" binding point for each
      texture unit (used by this API) and then "backup" binding points for the
      other targets (used by BindTexture).  This API would update the
      "primary" binding point but would only need to touch the "backup"
      binding points if something were bound there via BindTexture.  However,
      BindTexture would still be available and is commonly used today, so
      there would probably be little benefit.

    (17) For the BindTextures API, should the <first> parameter be an unsigned
         integer (0) or an enum (GL_TEXTURE0)?

      RESOLVED:  Use an integer unit number.

    (18) The BindImageTexture API not only binds a texture to an image unit,
         but also sets several additional pieces of state associated with an
         image unit (level, layered or not, selected layer, and image unit
         format).  How should this state be set?  Should we provide separate
         arrays for each extra parameter?

      RESOLVED:  Use "default" values for each image unit.  When unbinding
      textures, reset the state to API defaults (level zero, non-layered,
      layer zero, and R8 format).  When binding textures, bind all layers of
      level zero and take the format from the internal format of the texture
      level being bound.  Setting <layered> to TRUE in this case is not the
      default state, but it seems like the best default choice for cube map or
      array textures.  For textures without layers, the <layered> parameter
      has no effect, so this doesn't cause any problems with other targets
      like TEXTURE_2D.

      If an application wants to bind levels other than zero, select
      individual layers of a level for array textures, or use a format
      different from that of the texture, it will be necessary to do
      individual bindings via BindImageTexture.

    (19) If a texture bound to an image unit via BindImageTextures doesn't
         have a defined texture image (i.e., width = height = 0 for 2D
         textures), what internal format is associated with the binding?

      UNRESOLVED:  We will generate INVALID_OPERATION if there is no defined
      texture image.

      Note that even if a texture level has no texels defined, there is still
      an <internalformat> associated with the level, which can be queried with
      GetTexLevelParameter.  That value could be used, but it would still have
      to be checked to see if it's valid for image loads and stores.
      BindImageTexture doesn't accept all possible <format> enums.
      Additionally, the default internal format is profile-dependent:  core
      uses "RGBA", compatibility uses "1" (from OpenGL 1.0, meaning
      LUMINANCE).  Neither is accepted by BindImageTexture, though RGBA might
      be mapped internally by a driver to an internal format like RGBA8 that
      is accepted.

      Given the potential confusion over the internal format for zero-sized
      images and default internal formats, it's best to just not accept
      textures without defined images.

    (20) The BindBuffersRange and BindVertexBuffers accept arrays of "intptr"
         and "sizeiptr" values, which will have different sizes on 32- and
         64-bit architectures.  Is there any problem here?

      RESOLVED:  The API is fine.  Application developers will need to be
      careful to use the correct data type for the arrays it passes to these
      commands.  If the array passed to <offsets> is an array of "int" instead
      of "intptr", that code will typically work fine when compiled on 32-bit
      architectures if "int" types are stored as 32-bit values.  But if the
      same code is compiled for a 64-bit architecture, the array will be too
      small.  We expect that compilers will generate warnings and/or errors
      if the caller passes a pointer to the wrong type.

    (21) In the compatibility profile, can multi-bind commands be included in
         display lists?

      RESOLVED:  No.

    (22) What error should be generated when one of the names passed to a
         multi-bind command is not the name of an existing object?

      UNRESOLVED:  INVALID_OPERATION.  For the core profile, as well as for
      object types created since OpenGL 3.1, we have spec errors like the
      following for BindTexture:

        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.

      In issue (1), we decided that the multi-bind commands could not be used
      to create objects, whether or not the object names had previously been
      returned by commands like GenTextures.  The errors we require for the
      multi-bind commands are different from the BindTexture language quoted
      immmediately above only in the sense that the multi-bind will
      additionally throw an error if a texture name has been generated by
      GenTextures but the underlying texture object hasn't yet been created.
      However, the errors are similar enough that they should both throw the
      same error code (INVALID_OPERATION).


Revision History

    Revision 11, August 16, 2013 (Jon Leech)
      - Typo fix for BindBuffers* "offsets and strides" -> "offsets and
        sizes" (Bug 10685).
    Revision 10, July 21, 2013 (Jon Leech)
      - Specify that multibind commands are equivalent to repeated calls to
        the corresponding single bind commands except that objects are not
        created if they do not exist, matching issue 1. The other single
        bind commands do not create objects so this clarification is not
        needed for them (Bug 10486).

    Revision 9, May 30, 2013 (Jon Leech)
      - Fix typo for <offsets> "less than to zero" -> "less than zero". Use
        "<first> *through* <first> + <count> - 1" consistently.

    Revision 8, May 28, 2013
      - Change the error thrown when an object name passed to a multi-bind
        command doesn't yet exist from INVALID_VALUE to INVALID_OPERATION 
        (bug 10264).
      - Disallow the use of multi-bind commands in display lists (bug 10322).
      - Change the <count> parameter in multi-bind commands to use the type
        "sizei" to be consistent with other GL commands accepting a <count>
         parameter (bug 10323).
      - Clarify that passing NULL in arguments like <buffers> only affect
        bindings <first> through <first>+<count>-1 (bug 10289).
      - In the errors section for multi-bind commands, clarify which errors
        apply to only a single binding and which apply to the entire call (bug
        10289). 
      - Clarify in the spec language that BindImageTextures sets <access> to
        READ_WRITE for all bindings, which was already in the pseudocode (bug
        10289).
      - Use the term "general buffer binding" in spec language stating that
        BindBuffersBase and BindBuffersRange only affect numbered binding
        points (bug 10289).
      - Add issues (21) and (22).

    Revision 7, May 18, 2013
      - Fix typo in the description of BindSamplers.

    Revision 6, May 17, 2013
      - Modify the pseudocode for BindTextures to add in TEXTURE0 to the
        value passed to ActiveTexture, since it takes an enum and not an
        integer.

    Revision 5, May 10, 2013
      - Define lookupInternalFormat in pseudocode example.

    Revision 4, May 2, 2013
      - Renamed entry points for buffer bindings from BindBuffers() and
        BindBufferRanges() to BindBuffersBase() and BindBuffersRange(),
        respectively.
      - Add an INVALID_OPERATION error if a non-zero texture passed to
        BindImageTextures() does not have a defined image array.
      - Add an "unless otherwise noted" qualification to the general spec rule
        that commands producing errors do not modify the GL state.  Multi-bind
        commands have special error behavior discussed in issue (11).
      - Mark issues resolved based on previous spec reviews.
      - Added issue (20).

    Revision 3, April 19, 2013
      - Add a BindImageTextures API to bind a collection of textures to image
        units (for shader image loads/stores).
      - Fix the spec to consistently use the parameter name <first> to
        identify the first binding point to update.
      - Add new issues.

    Revision 2, January 20, 2013
      - Fix various specification errors.
      - Add an issue about whether we should provide a multi-bind API for
        framebuffer object attachments.

    Revision 1, January 18, 2013
      - Initial revision.