extensions/MESA/MESA_map_buffer_client_pointer.txt

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( sizeiptr *size );


New Types

    None

New Tokens

    Accepted by the <access> parameter of MapBufferRange:

        MAP_CLIENT_POINTER_BIT_MESA                0x4000

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

        BUFFER_CLIENT_POINTER_SIZE_MESA            0x9790


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

    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.

    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 added ranges are global
        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
        reacquire the pages, first unmap any buffers in the range, call Flush,
        and thence

            void *ReleaseClientPointerRangeMESA( sizeiptr *size );

        will return the range back to the application, with <size> relaying
        back the size of the returned range. 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.


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.

Revision History

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