1Name
2
3    ARB_map_buffer_alignment
4
5Name Strings
6
7    GL_ARB_map_buffer_alignment
8
9Contact
10
11    Piers Daniell, NVIDIA Corporation (pdaniell 'at' nvidia.com)
12
13Contributors
14
15    Jeff Bolz, NVIDIA
16    Pat Brown, NVIDIA
17
18Notice
19
20    Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at
21        http://www.khronos.org/registry/speccopyright.html
22
23Specification Update Policy
24
25    Khronos-approved extension specifications are updated in response to
26    issues and bugs prioritized by the Khronos OpenGL Working Group. For
27    extensions which have been promoted to a core Specification, fixes will
28    first appear in the latest version of that core Specification, and will
29    eventually be backported to the extension document. This policy is
30    described in more detail at
31        https://www.khronos.org/registry/OpenGL/docs/update_policy.php
32
33Status
34
35    Complete. Approved by the ARB on 2011/06/20.
36    Approved by the Khronos Promoters on 2011/07/29.
37
38Version
39
40    Last Modified Date:         July 28, 2011
41    Revision:                   5
42
43Number
44
45    ARB Extension #113
46
47Dependencies
48
49    OpenGL 2.1 is required.
50    
51    If ARB_map_buffer_range is NOT supported, ignore references to
52    MapBufferRange.
53    
54    This extension is written against The OpenGL 4.1 (Compatibility Profile)
55    specification.
56
57Overview
58
59    This extension adds a requirement to the pointer returned by MapBuffer
60    and MapBufferRange that they provide a minimum of 64 byte alignment to
61    support processing of the data directly with special CPU instructions
62    like SSE and AVX.
63
64New Procedures and Functions
65
66    None
67
68New Tokens
69
70    Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
71    GetInteger64v, GetFloatv, and GetDoublev:
72
73        MIN_MAP_BUFFER_ALIGNMENT                        0x90BC
74
75Changes to Section 2.9.3 (Mapping and Unmapping Buffer Data), page 60
76
77    In the third paragraph of the section that starts:
78    
79    "Pointer values returned by MapBufferRange may not be passed..."
80    
81    insert the following sentence at the start of the paragraph:
82    
83    "If no error occurs, the pointer value returned by MapBufferRange must
84    reflect an allocation aligned to the value of MIN_MAP_BUFFER_ALIGNMENT
85    basic machine units.  Subtracting <offset> basic machine units from the
86    returned pointer will always produce a multiple of the value of
87    MIN_MAP_BUFFER_ALIGNMENT."
88    
89    On page 63, which describes MapBuffer, after the sentence that ends:
90    
91    "... value of the access enum parameter passed to MapBuffer."
92    
93    Add the following sentence:
94    
95    "The pointer value returned by MapBuffer must be aligned to
96    the value of MIN_MAP_BUFFER_ALIGNMENT basic machine units."
97    
98Additions to the AGL/GLX/WGL Specifications
99
100    None
101
102Errors
103
104    None
105
106New State
107
108    None
109
110New Implementation Dependent State
111
112    Get Value                        Type  Get Command     Minimum Value    Description             Sec.     Attribute
113    ---------                        ----  -----------     -------------    -------------------     -----    ---------
114    MIN_MAP_BUFFER_ALIGNMENT         Z+    GetIntegerv     64               Minimum byte alignment  2.9.3    -
115                                                                            of the pointer returned
116                                                                            by MapBuffer and
117                                                                            MapBufferRange.
118
119Issues
120
121    1) Why 64 byte alignment and not 16 (like DX) or something else?
122    
123    RESOLVED: A 16 byte alignment is good for SSE, which uses a 128 bit
124    register file. However, with the advent of AVX, which has a 256 bit
125    register file, and the potential for even wider register files in the
126    near future, 64 byte alignment seemed like a safe choice.
127
128    2) What alignment should be used for MapBufferRange when <offset> is
129    non-zero?
130
131    RESOLVED:  The pointer returned should be consistent with the base of the
132    buffer being aligned.  For example, if a buffer was mapped with an
133    <offset> of 24 bytes on an implementation with a
134    MIN_MAP_BUFFER_ALIGNMENT of 64, the value of the pointer returned
135    would have a value of the form 64*<N>+24 for some integer <N>.
136
137    3) How should the minimum alignment be exposed?
138
139    RESOLVED:  Provide an implementation-dependent constant that can be
140    queried.  Implementations that align buffers to >64-byte boundaries for
141    whatever reason could advertise higher alignment values.  Since the
142    minimum alignment is 64 bytes, an application using this extension need
143    not check the implementation's advertised alignment unless it requires an
144    alignment larger than this minimum.
145
146Revision History
147
148    Rev.    Date    Author    Changes
149    ----  --------  --------  -----------------------------------------------
150    5     07/28/11  pbrown    Rename MINIMUM_MAP_BUFFER_ALIGNMENT to
151                              MIN_MAP_BUFFER_ALIGNMENT to match usual API
152                              naming conventions (bug 7825).
153
154    4     06/20/11  pdaniell  Assign enum value.
155    
156    3     06/06/11  Jon Leech Minor typos for consistency with core spec.
157
158    2     05/19/11  pbrown    Change spec language to require MapBufferRange
159                              to return a pointer consistent with the base
160                              being aligned.  Add a couple issues.  Minor 
161                              wording changes (bug 7663).
162
163    1     05/05/11  pdaniell  Initial version.
164