xref: /third_party/openGLES/extensions/APPLE/APPLE_flush_buffer_range.txt

Name

    APPLE_flush_buffer_range

Name Strings

    GL_APPLE_flush_buffer_range

Contact

    Chris Niederauer, Apple (ccn 'at' apple.com)

Status

    Shipping on Mac OS X.

Version

    Last Modified Date: 19 March 2008
    Author Revision: 1.1

Number

    321

Dependencies

    Buffer Objects as per ARB_vertex_buffer_object or OpenGL 1.5 are required.

    If ARB_pixel_buffer_object is NOT supported and the OpenGL version is less
    than 2.1, ignore references to PIXEL_UNPACK_BUFFER and PIXEL_PACK_BUFFER.

    If APPLE_fence or similar fencing mechanism is NOT suppported, Finish can
    be used in place of TestObject, FinishObject, TestFence and FinishFence.

    Written based on the wording of the OpenGL 2.1 specification.

Overview

    APPLE_flush_buffer_range expands the buffer object API to allow greater
    performance when a client application only needs to write to a sub-range
    of a buffer object. To that end, this extension introduces two new buffer
    object features: non-serialized buffer modification and explicit sub-range
    flushing for mapped buffer objects.

    OpenGL requires that commands occur in a FIFO manner meaning that any
    changes to buffer objects either block until the data has been processed by
    the OpenGL pipeline or else create extra copies to avoid such a block.  By
    providing a method to asynchronously modify buffer object data, an
    application is then able to manage the synchronization points themselves
    and modify ranges of data contained by a buffer object even though OpenGL
    might still be using other parts of it.

    This extension also provides a method for explicitly flushing ranges of a
    mapped buffer object so OpenGL does not have to assume that the entire
    range may have been modified.

    Affects ARB_vertex_buffer_object, ARB_pixel_buffer_object and OpenGL 1.5
    Buffer Objects.

Issues

    Should the ability to update other Buffer Object state such as BUFFER_SIZE
    and BUFFER_USAGE be added to BufferParameteriAPPLE?

        RESOLVED:  No.  API already exists for setting this state and allowing
        this new API to update this state would add more semantics that this
        extension is not trying to address.  Also as decided when working on
        the ARB_vertex_buffer_object extension: "It is desirable for the
        implementation to know the usage when the buffer is initialized, so
        including it in the initialization command makes sense."

    Should a MapSubBuffer API be added to avoid having the application manually
    flush memory which is not modified within a buffer object?

        RESOLVED:  No.  An application may still want to modify multiple
        sections of a buffer object simultaneously such as for procedural data
        and providing a range flushing routine allows an implementation to
        effectively achieve the same performance benefits.

        Secondly, providing a MapSubBuffer routine might be confusing to
        developers as one might think that MapSubBuffers could know which
        sections need to block or provide temporary intermediary buffers and
        in theory achieve the same benefits as adding a flag that states that
        the application would like to asynchronously modify some buffer object
        data; however, implementing a "smart" MapSubBuffer function would be
        difficult to make efficient.

    When flushing ranges manually, should new API be added or should
    BufferSubData be overloaded?

        RESOLVED:  New API should be added specifically for this task.  Trying
        to override BufferSubData becomes cumbersome for many reasons.  In
        order to use BufferSubData, the behavior would need to change when
        called inside of a MapBuffer/UnmapBuffer pair to not throw an error and
        the <data> parameter would then either not be used or cause a specific
        behavior.  It is much simpler to provide new API specifically targeted
        at the task of manually flushing memory regions.  This is also less
        prone to errors in legacy applications that may incorrectly use
        BufferSubData in situations that should cause invalid operation errors
        prior to the introduction of this extension.

New Procedures and Functions

    void BufferParameteriAPPLE(enum target, enum pname, int param);

    void FlushMappedBufferRangeAPPLE(enum target, intptr offset,
                                     sizeiptr size);

New Tokens

    Accepted by the <pname> parameter of BufferParameteriAPPLE and
    GetBufferParameteriv:

        BUFFER_SERIALIZED_MODIFY_APPLE      0x8A12
        BUFFER_FLUSHING_UNMAP_APPLE         0x8A13

Additions to Chapter 2 of the OpenGL 2.0 Specification (Buffer Objects)

    - (2.9, p. 33) Add new BufferParameter parameters:

    Add to Table 2.6 (p. 34):

        Name                             Type     Initial Value   Legal Values
        ------------------------------   -------  -------------   ------------
        BUFFER_SERIALIZED_MODIFY_APPLE   boolean      TRUE        TRUE, FALSE
        BUFFER_FLUSHING_UNMAP_APPLE      boolean      TRUE        TRUE, FALSE

    Change Table 2.7 (p. 36) caption to:

        Table 2.7: Buffer object state set by BufferData.

    Add to the end of Section 2.9 (p. 38):

    The serialized modification and flushing unmap parameters are specified by
    calling

        void BufferParameteriAPPLE(enum target, enum pname, int param);

    with <target> set to one of ARRAY_BUFFER, ELEMENT_ARRAY_BUFFER,
    PIXEL_UNPACK_BUFFER, or PIXEL_PACK_BUFFER.  <pname> is one of
    BUFFER_SERIALIZED_MODIFY_APPLE or BUFFER_FLUSHING_UNMAP_APPLE and <param>
    specifies the new value for parameter <pname>.
        By setting the value of the parameter BUFFER_SERIALIZED_MODIFY_APPLE to
    FALSE, the client must then manually synchronize any modifcations to the
    buffer object data and usage by OpenGL.  In order to maintain coherency
    when BUFFER_SERIALIZED_MODIFY_APPLE is disabled, synchronization must be
    done after drawing with a buffer object prior to mapping its data for
    modification using fences.  A fence, such as the type of fence defined in
    the APPLE_fence extension, allows selective synchronization.  The client
    can set a fence immediately after drawing with the data in question and
    test or finish that fence prior to calling MapBuffer or BufferSubData.
    This serialization relaxation also applies to all OpenGL commands which may
    write to a buffer object such as ReadPixels and GetTexImage.
        Setting the value of the parameter BUFFER_FLUSHING_UNMAP_APPLE to FALSE
    allows the client to specify regions of a mapped buffer object that have
    been modified by calling

        void FlushMappedBufferRangeAPPLE(enum target, intptr offset,
                                         sizeiptr size);

    prior to unmapping.  <target> must be set to one of ARRAY_BUFFER,
    ELEMENT_ARRAY_BUFFER, PIXEL_UNPACK_BUFFER, or PIXEL_PACK_BUFFER.  <offset>
    and <size> indicate the range of data in the buffer object that has been
    modified in terms of basic machine units.  An INVALID_VALUE error is
    generated if <offset> or <size> is less than zero, or if <offset> + <size>
    is greater than the value of BUFFER_SIZE. When BUFFER_FLUSHING_UNMAP_APPLE
    is set to FALSE, FlushMappedBufferRangeAPPLE must be called on all modified
    ranges of a mapped buffer object after the data within each specified range
    has been modified and prior to unmapping it, allowing OpenGL to flush only
    the portions of the buffer object that have been modified.  Any modified
    ranges of a mapped buffer object that are not explicitly flushed prior to
    unmapping when BUFFER_FLUSHING_UNMAP_APPLE is set to FALSE become
    undefined.

Errors

    INVALID_ENUM is generated if the <target> parameter of
    BufferParameteriAPPLE and FlushMappedBufferRangeAPPLE is not ARRAY_BUFFER,
    ELEMENT_ARRAY_BUFFER, PIXEL_PACK_BUFFER or PIXEL_UNPACK_BUFFER.

    INVALID_ENUM is generated if the <pname> parameter of BufferParameteriAPPLE
    is not BUFFER_SERIALIZED_MODIFY_APPLE or BUFFER_NON_FLUSHING_UNMAP_APPLE.

    INVALID_OPERATION is generated if BufferParameteriAPPLE or
    FlushMappedBufferRangeAPPLE is executed while zero is bound to the <target>
    parameter.

    INVALID_OPERATION is generated if FlushMappedBufferRangeAPPLE is called
    outside the execution of a MapBuffer and the corresponding execution of
    UnmapBuffer.

    INVALID_OPERATION may be generated if any of the commands defined in this
    extension is executed between the execution of Begin and the corresponding
    execution of End.

    INVALID_VALUE is generated if the <offset> or <size> parameters of
    FlushMappedBufferRangeAPPLE are negative.

    INVALID_VALUE is generated if the <offset> and <size> parameters of
    FlushMappedBufferRangeAPPLE define a region of memory that extends beyond
    that allocated by BufferData.

New State

    Add to Table 6.9 (p. 274):
                                                                Initial
    Get Value                       Type  Get Command            Value   Description                     Sec  Attrib
    ------------------------------  ----  --------------------  -------  ------------------------------  ---  ------
    BUFFER_SERIALIZED_MODIFY_APPLE   B    GetBufferParameteriv   TRUE    Buffer serialized modify param  2.9    -
    BUFFER_FLUSHING_UNMAP_APPLE      B    GetBufferParameteriv   TRUE    Buffer flushing unmap param     2.9    -

New Implementation Dependent State

    None

Usage Examples

    This extension can be used in place of using multiple buffer objects for
    applications that may have algorithms that can not efficiently use the
    existing buffer object API.

    Convenient macro definition for specifying buffer offsets:

        #define BUFFER_OFFSET(i) ((char *)NULL + (i))

    Example of updating small amounts of data in a large VBO:

        //  setup time
        glBindBuffer(GL_ARRAY_BUFFER, my_vbo);
        glBufferData(GL_ARRAY_BUFFER, size, data, GL_DYNAMIC_DRAW);
        glBufferParameteriAPPLE(GL_ARRAY_BUFFER, GL_BUFFER_FLUSHING_UNMAP_APPLE, GL_FALSE);

        //  update/draw time
        glBindBuffer(GL_ARRAY_BUFFER, my_vbo);
        GLvoid *data = glMapBuffer(GL_ARRAY_BUFFER, GL_WRITE_ONLY);
        for i to n {
            if (need_to_change_region_i) {
                //  modify region i
                glFlushMappedBufferRangeAPPLE(GL_ARRAY_BUFFER, BUFFER_OFFSET(region_i_offset), region_i_size);
            }
        }
        glUnmapBuffer(GL_ARRAY_BUFFER);
        //  draw from vertex data in buffer object

    Example of updating sections of a VBO serializing with APPLE_fence:

        //  setup time
        glBindBuffer(GL_ARRAY_BUFFER, my_vbo);
        glBufferData(GL_ARRAY_BUFFER, size, data, GL_DYNAMIC_DRAW);
        glBufferParameteriAPPLE(GL_ARRAY_BUFFER, GL_BUFFER_SERIALIZING_MODIFY_APPLE, GL_FALSE);
        glBufferParameteriAPPLE(GL_ARRAY_BUFFER, GL_BUFFER_FLUSHING_UNMAP_APPLE, GL_FALSE);

        //  update/draw time
        glBindBuffer(GL_ARRAY_BUFFER, my_vbo);
        while(!glTestFenceAPPLE(current_regions_fence))
        {
            //  Do some more work if OpenGL is still using the
            //  portions of the VBO that we want to modify.
        }
        GLvoid *data = glMapBuffer(GL_ARRAY_BUFFER, GL_WRITE_ONLY);
        for i to n in regions {
            if (need_to_change_region_i) {
                //  modify region i
                glFlushMappedBufferRangeAPPLE(GL_ARRAY_BUFFER, BUFFER_OFFSET(region_i_offset), region_i_size);
            }
        }
        glUnmapBuffer(GL_ARRAY_BUFFER);
        //  draw from vertex data in region and set appropriate fence afterward

Revision History

    03/19/2008    1.1
        - Introduced errors when FlushMappedBufferRangeAPPLE is given bad
          offset or size parameters.
        - Clarified that FlushMappedBufferRangeAPPLE must be called after the
          data in the mapped buffer object range has been modified.

    10/04/2006    1.0
        - Initial public revision.