Name

    MESA_map_buffer_client_pointer

Name Strings

    GL_MESA_map_buffer_client_pointer

Contact

    Derek Lesho <dlesho@codeweavers.com>

Contributors

    Derek Lesho, Codeweavers

Status

    Proposal

Version

    Version 1, February, 2026

Number

    OpenGL Extension 562

Dependencies

    OpenGL 3.0 or ARB_map_buffer_ranged is required.

    This extension is written against the OpenGL 4.6 (Core Profile)
    Specification.

Overview

    This extension allows the application to specify pointer ranges within
    which buffers should be mapped.

    This extension is proposed to help the WINE project [https://winehq.org],
    which implements the 32-bit Windows OpenGL ABI on top of 64-bit Linux,
    return an address in the 32-bit address range from Map(Named)Buffer(Range).

IP Status

    None

Issues

    None

New Procedures and Functions

    void AddClientPointerRangeMESA( void *addr, sizeiptr size );

    void *ReleaseClientPointerRangeMESA( bitfield flags,
                                         sizeiptr *size );


New Types

    None

New Tokens

    Accepted by the <access> parameter of MapBufferRange and <flags> parameter
    of BufferStorage:

        MAP_CLIENT_POINTER_BIT_MESA                0x4000

    Accepted by the <pname> parameter of GetBufferParameter{i|i64}v:

        BUFFER_CLIENT_POINTER_SIZE_MESA            0x9790

    Accepted by the <flags> parameter of ReleaseClientPointerRangeMESA:

        CLIENT_POINTER_RELEASE_ALL_MESA            0x0001

    Accepted by the <usage> parameter of BufferData:

        GL_CLIENT_POINTER_STREAM_DRAW_MESA         0x9791
        GL_CLIENT_POINTER_STREAM_READ_MESA         0x9792
        GL_CLIENT_POINTER_STREAM_COPY_MESA         0x9793
        GL_CLIENT_POINTER_STATIC_DRAW_MESA         0x9794
        GL_CLIENT_POINTER_STATIC_READ_MESA         0x9795
        GL_CLIENT_POINTER_STATIC_COPY_MESA         0x9796
        GL_CLIENT_POINTER_DYNAMIC_DRAW_MESA        0x9797
        GL_CLIENT_POINTER_DYNAMIC_READ_MESA        0x9798
        GL_CLIENT_POINTER_DYNAMIC_COPY_MESA        0x9799


Additions to Chapter 6 of the OpenGL Core Profile Specification, Version 4.6,
"Buffer Objects"

    Modify Section 6.2, "Creating and Modifying Buffer Object Data Stores"

    Add to the list of accepted values for the <flags> parameter to
    BufferStorage, p.66.

        MAP_CLIENT_POINTER_BIT_MESA   The data store can only be mapped onto an
    address range provided by AddClientPointerRangeMESA.

    Add to the the list of accepted values for the <usage> parameter to
    BufferData, p.69.

        CLIENT_POINTER_* The data store usage is defined identically to the
    value without the CLIENT_POINTER suffix, and the value of
    BUFFER_STORAGE_FLAGS will include MAP_CLIENT_POINTER_BIT_MESA.

    Modify Table 6.3, "Buffer object state after calling BufferData,
            BufferStorage, or NamedBufferStorage.":

    Name                 | Value for                   | Value for
                         | BufferData                  | BufferStorage
    ---------------------+-----------------------------+---------------
    BUFFER_STORAGE_FLAGS | MAP_READ_BIT |              |  <flags>
                         | MAP_WRITE_BIT |             |
                         | DYNAMIC_STORAGE_BIT         |
                         | and |                       |
                         | MAP_CLIENT_POINTER_BIT_MESA |
                         | if the value of <usage> is  |
                         | is CLIENT_POINTER_*         |

    Modify Section 6.3, "Mapping and Unmapping Buffer Data"

    Add to the bulleted list describing flags that modify buffer mappings,
    p.73.

        * MAP_CLIENT_POINTER_BIT_MESA indicates the mapped buffer pointer must
          be in an address range provided by AddClientPointerRangeMESA. If no
          space is found here, an OUT_OF_MEMORY error is generated. The value
          of BUFFER_STORAGE_FLAGS for the buffer being mapped must share the
          same MAP_CLIENT_POINTER_BIT_MESA bit as <access>.

    Append to Section 6.3 "Mapping and Unmapping Buffer Data", p.78.

        If a buffer is mapped with the MAP_CLIENT_POINTER_BIT_MESA flag, the
        returned pointer will be in a range provided by the application through

            void AddClientPointerRangeMESA( void *addr, sizeiptr size );

        with <addr> set to the start of a page-aligned address range of size
        <size> with read and write permissions.

        The range will be held as client state, and if needed consumed by a
        call to MapBufferRange with access including
        MAP_CLIENT_POINTER_BIT_MESA. It is an error to provide a new range
        AddClientPointerRangeMESA again before the previous is range consumed
        or released. To ensure this, call ReleaseClientPointerRange if MapRange
        fails after AddClientPointerRangeMESA.

        The consumed range is shareable server state which may be used and
        reused for any buffers mapped with <access> including
        MAP_CLIENT_POINTER_BIT_MESA. The driver will hold this address range as
        long as any buffers are mapped in it. To reclaim the range, first unmap
        any buffers in the range, call Flush, and thence

            void *ReleaseClientPointerRangeMESA( bitfield flags,
                                                 sizeiptr *size );

        will return the range back to the application, with <size> relaying
        back the size of the returned range. If CLIENT_POINTER_RELEASE_ALL_MESA
        is set in <flags>, the driver must release all client pointer ranges
        that don't contain a currently mapped buffer pointer. Otherwise, the
        driver may hold onto unused mappings which can be reused.

        While the pages sit in the driver, memory access in any manner other
        than as defined by Map(Named)BufferRange is not permitted, and results
        in undefined behavior.

        If no range can be released, ReleaseClientPointerRange will return
        NULL.


Errors

    An OUT_OF_MEMORY error is generated by Map(Named)BufferRange if
    MAP_CLIENT_POINTER_BIT_MESA is included in <access> but no space can be
    found for a mapping in the ranges provided by AddClientPointerRangeMESA. In
    this case, the buffer object state value BUFFER_CLIENT_POINTER_SIZE_MESA is
    set to the size required of a new client pointer range to enable mapping
    the buffer with MAP_CLIENT_POINTER_BIT_MESA.

    An INVALID_OPERATION error is generated by Map(Named)BufferRange if the
    MAP_CLIENT_POINTER_BIT_MESA bit in <access> isn't equal to the
    MAP_CLIENT_POINTER_BIT_MESA bit in BUFFER_STORAGE_FLAGS.

    An INVALID_OPERATION error is generated by AddClientPointerRangeMESA if a
    previous range hasn't yet been consumed or released.

Revision History

    Version 2, 2026-7-28 (Derek Lesho)
        - CLIENT_POINTER_RELEASE_ALL_MESA flag
        - CLIENT_POINTER buffer storage flag
        - Specify shareable state

    Version 1, 2026-2-25 (Derek Lesho)
        Initial draft.
