1Name
2
3    ANGLE_external_objects_flags
4
5Name Strings
6
7    GL_ANGLE_memory_object_flags
8
9Contributors
10
11    Shahbaz Youssefi, Google
12
13Contact
14
15    Shahbaz Youssefi, Google (syoussefi 'at' google.com)
16
17Status
18
19    Draft
20
21Version
22
23    Last Modified Date: Aug 3, 2020
24    Revision: 1
25
26Number
27
28    TBD
29
30Dependencies
31
32    Written against the OpenGL 4.5 and OpenGL ES 3.2 specifications
33
34    GL_ANGLE_memory_object_flags requires GL_EXT_memory_object.
35
36Overview
37
38    Building upon the OpenGL memory object framework defined in
39    EXT_external_objects, this extension introduces new Texture entry points
40    for specifying create and usage flags parameters.  These parameters match
41    an external Texture's corresponding Vulkan create and usage flags.  This
42    allows applications to drop usage flags that are detrimental to
43    performance, or add create flags as necessary.
44
45New Procedures and Functions
46
47    The following commands are added:
48
49        void TexStorageMemFlags2DANGLE(enum target,
50                                       sizei levels,
51                                       enum internalFormat,
52                                       sizei width,
53                                       sizei height,
54                                       uint memory,
55                                       uint64 offset,
56                                       bitfield createFlags,
57                                       bitfield usageFlags);
58
59        void TexStorageMemFlags2DMultisampleANGLE(enum target,
60                                                  sizei samples,
61                                                  enum internalFormat,
62                                                  sizei width,
63                                                  sizei height,
64                                                  boolean fixedSampleLocations,
65                                                  uint memory,
66                                                  uint64 offset,
67                                                  bitfield createFlags,
68                                                  bitfield usageFlags);
69
70        void TexStorageMemFlags3DANGLE(enum target,
71                                       sizei levels,
72                                       enum internalFormat,
73                                       sizei width,
74                                       sizei height,
75                                       sizei depth,
76                                       uint memory,
77                                       uint64 offset,
78                                       bitfield createFlags,
79                                       bitfield usageFlags);
80
81        void TexStorageMemFlags3DMultisampleANGLE(enum target,
82                                                  sizei samples,
83                                                  enum internalFormat,
84                                                  sizei width,
85                                                  sizei height,
86                                                  sizei depth,
87                                                  boolean fixedSampleLocations,
88                                                  uint memory,
89                                                  uint64 offset,
90                                                  bitfield createFlags,
91                                                  bitfield usageFlags);
92
93        [[ The following are added if direct state access is supported ]]
94
95        void TextureStorageMemFlags2DANGLE(uint texture,
96                                           sizei levels,
97                                           enum internalFormat,
98                                           sizei width,
99                                           sizei height,
100                                           uint memory,
101                                           uint64 offset,
102                                           bitfield createFlags,
103                                           bitfield usageFlags);
104
105        void TextureStorageMemFlags2DMultisampleANGLE(uint texture,
106                                                      sizei samples,
107                                                      enum internalFormat,
108                                                      sizei width,
109                                                      sizei height,
110                                                      boolean fixedSampleLocations,
111                                                      uint memory,
112                                                      uint64 offset,
113                                                      bitfield createFlags,
114                                                      bitfield usageFlags);
115
116        void TextureStorageMemFlags3DANGLE(uint texture,
117                                           sizei levels,
118                                           enum internalFormat,
119                                           sizei width,
120                                           sizei height,
121                                           sizei depth,
122                                           uint memory,
123                                           uint64 offset,
124                                           bitfield createFlags,
125                                           bitfield usageFlags);
126
127        void TextureStorageMemFlags3DMultisampleANGLE(uint texture,
128                                                      sizei samples,
129                                                      enum internalFormat,
130                                                      sizei width,
131                                                      sizei height,
132                                                      sizei depth,
133                                                      boolean fixedSampleLocations,
134                                                      uint memory,
135                                                      uint64 offset,
136                                                      bitfield createFlags,
137                                                      bitfield usageFlags);
138
139        [[ The following are available in OpenGL only ]]
140
141        void TexStorageMemFlags1DANGLE(enum target,
142                                       sizei levels,
143                                       enum internalFormat,
144                                       sizei width,
145                                       uint memory,
146                                       uint64 offset,
147                                       bitfield createFlags,
148                                       bitfield usageFlags);
149
150        [[ The following are availble in OpenGL only, and only when
151           direct state access is available ]]
152
153        void TextureStorageMemFlags1DANGLE(uint texture,
154                                           sizei levels,
155                                           enum internalFormat,
156                                           sizei width,
157                                           uint memory,
158                                           uint64 offset,
159                                           bitfield createFlags,
160                                           bitfield usageFlags);
161
162New Tokens
163
164    The following tokens are added:
165
166    Accepted by the <createFlags> parameter of TexStorageMemFlags*ANGLE() and
167    TextureStorageMemFlags*ANGLE().
168
169        CREATE_SPARSE_BINDING_BIT_ANGLE                    0x00000001
170        CREATE_SPARSE_RESIDENCY_BIT_ANGLE                  0x00000002
171        CREATE_SPARSE_ALIASED_BIT_ANGLE                    0x00000004
172        CREATE_MUTABLE_FORMAT_BIT_ANGLE                    0x00000008
173        CREATE_CUBE_COMPATIBLE_BIT_ANGLE                   0x00000010
174        CREATE_ALIAS_BIT_ANGLE                             0x00000400
175        CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_ANGLE       0x00000040
176        CREATE_2D_ARRAY_COMPATIBLE_BIT_ANGLE               0x00000020
177        CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_ANGLE       0x00000080
178        CREATE_EXTENDED_USAGE_BIT_ANGLE                    0x00000100
179        CREATE_PROTECTED_BIT_ANGLE                         0x00000800
180        CREATE_DISJOINT_BIT_ANGLE                          0x00000200
181        CREATE_CORNER_SAMPLED_BIT_ANGLE                    0x00002000
182        CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_ANGLE 0x00001000
183        CREATE_SUBSAMPLED_BIT_ANGLE                        0x00004000
184
185    Accepted by the <usageFlags> parameter of TexStorageMemFlags*ANGLE() and
186    TextureStorageMemFlags*ANGLE().
187
188        USAGE_TRANSFER_SRC_BIT_ANGLE                       0x00000001
189        USAGE_TRANSFER_DST_BIT_ANGLE                       0x00000002
190        USAGE_SAMPLED_BIT_ANGLE                            0x00000004
191        USAGE_STORAGE_BIT_ANGLE                            0x00000008
192        USAGE_COLOR_ATTACHMENT_BIT_ANGLE                   0x00000010
193        USAGE_DEPTH_STENCIL_ATTACHMENT_BIT_ANGLE           0x00000020
194        USAGE_TRANSIENT_ATTACHMENT_BIT_ANGLE               0x00000040
195        USAGE_INPUT_ATTACHMENT_BIT_ANGLE                   0x00000080
196        USAGE_SHADING_RATE_IMAGE_BIT_ANGLE                 0x00000100
197        USAGE_FRAGMENT_DENSITY_MAP_BIT_ANGLE               0x00000200
198
199Additions to Chapter 8 of the OpenGL 4.5 Specification (Textures and
200Samplers)
201
202    For each list of TexStorage* commands in the 1D, 2D, 3D,
203    2DMultisample, and 3DMultisample families, add the following
204    variants:
205
206        void TexStorageMemFlags*ANGLE(<existing parameters>,
207                                      uint memory,
208                                      uint64 offset,
209                                      bitfield createFlags,
210                                      bitfield usageFlags);
211
212        void TextureStorageMemFlags*ANGLE(<existing parameters>,
213                                          uint memory,
214                                          uint64 offset,
215                                          bitfield createFlags,
216                                          bitfield usageFlags);
217
218    For each of the TexStorageMemFlags*ANGLE commands, move the description from
219    the corresponding TexStorageMem*EXT from EXT_external_objects under that
220    command and add the following language:
221
222        "The implementation should apply the same semantics to the internal
223        storage of the texture based on <createFlags> and <usageFlags> as the
224        corresonding VK_IMAGE_CREATE_* and VK_IMAGE_USAGE_* flags would have on
225        a Vulkan image respectively.  See tables 8.17 and 8.18 for the mapping
226        between the GL and Vulkan flags.  It is undefined behavior if the
227        application provides create and usage flags that are not identical to
228        those used to create the Vulkan image."
229
230        Table 8.17: Create flags and corresponding Vulkan Image Create Flags
231
232        | Create Flag                                        | Equivalent Vulkan Create Flag                             |
233        +----------------------------------------------------+-----------------------------------------------------------+
234        | CREATE_SPARSE_BINDING_BIT_ANGLE                    | VK_IMAGE_CREATE_SPARSE_BINDING_BIT                        |
235        | CREATE_SPARSE_RESIDENCY_BIT_ANGLE                  | VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT                      |
236        | CREATE_SPARSE_ALIASED_BIT_ANGLE                    | VK_IMAGE_CREATE_SPARSE_ALIASED_BIT                        |
237        | CREATE_MUTABLE_FORMAT_BIT_ANGLE                    | VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT                        |
238        | CREATE_CUBE_COMPATIBLE_BIT_ANGLE                   | VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT                       |
239        | CREATE_ALIAS_BIT_ANGLE                             | VK_IMAGE_CREATE_ALIAS_BIT                                 |
240        | CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_ANGLE       | VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT           |
241        | CREATE_2D_ARRAY_COMPATIBLE_BIT_ANGLE               | VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT                   |
242        | CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT_ANGLE       | VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT           |
243        | CREATE_EXTENDED_USAGE_BIT_ANGLE                    | VK_IMAGE_CREATE_EXTENDED_USAGE_BIT                        |
244        | CREATE_PROTECTED_BIT_ANGLE                         | VK_IMAGE_CREATE_PROTECTED_BIT                             |
245        | CREATE_DISJOINT_BIT_ANGLE                          | VK_IMAGE_CREATE_DISJOINT_BIT                              |
246        | CREATE_CORNER_SAMPLED_BIT_ANGLE                    | VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV                     |
247        | CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_ANGLE | VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT |
248        | CREATE_SUBSAMPLED_BIT_ANGLE                        | VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT                        |
249        +----------------------------------------------------------------------------------------------------------------+
250
251        Table 8.18: Usage flags and corresponding Vulkan Image Usage Flags
252
253        | Usage Flag                               | Equivalent Vulkan Usage Flag                |
254        +------------------------------------------+---------------------------------------------+
255        | USAGE_TRANSFER_SRC_BIT_ANGLE             | VK_IMAGE_USAGE_TRANSFER_SRC_BIT             |
256        | USAGE_TRANSFER_DST_BIT_ANGLE             | VK_IMAGE_USAGE_TRANSFER_DST_BIT             |
257        | USAGE_SAMPLED_BIT_ANGLE                  | VK_IMAGE_USAGE_SAMPLED_BIT                  |
258        | USAGE_STORAGE_BIT_ANGLE                  | VK_IMAGE_USAGE_STORAGE_BIT                  |
259        | USAGE_COLOR_ATTACHMENT_BIT_ANGLE         | VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT         |
260        | USAGE_DEPTH_STENCIL_ATTACHMENT_BIT_ANGLE | VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT |
261        | USAGE_TRANSIENT_ATTACHMENT_BIT_ANGLE     | VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT     |
262        | USAGE_INPUT_ATTACHMENT_BIT_ANGLE         | VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT         |
263        | USAGE_SHADING_RATE_IMAGE_BIT_ANGLE       | VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV    |
264        | USAGE_FRAGMENT_DENSITY_MAP_BIT_ANGLE     | VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT |
265        +----------------------------------------------------------------------------------------+
266
267    Add the following errors for each of the TexStorageMemFlags*ANGLE commands:
268
269        "An INVALID_VALUE error is generated if <createFlags> has a bit set
270        other than those specified in table 8.17."
271
272        "An INVALID_VALUE error is generated if <usageFlags> has a bit set
273        other than those specified in table 8.18."
274
275    For each of the TexStorageMem*EXT commands, change the description of
276    TexStorageMem*EXT and TextureStorageMem*EXT as such:
277
278        "Calling TexStorageMem*EXT is equivalent to calling
279        TexStorageMemFlags*ANGLE with 0 as <createFlags> and all
280        Vulkan-supported usage flags, even if there are no corresponding GL
281        flags specified in this extension."
282
283Issues
284
285    1)  Can the GL and Vulkan create and usage flag values diverge?
286
287        RESOLVED: No.  It is expected for the application to provide the flags
288        used to create the Vulkan image verbatim.
289
290    2)  What if Vulkan adds new create and usage flags?
291
292        RESOLVED: If the implementation is too old to be aware of those flags,
293        the functions from GL_EXT_memory_object must be used instead.  New flags
294        can be added through new extensions that build on this extension.
295
296    3)  Should the GL implementation apply the same validation as Vulkan based
297        on the create and usage flags?
298
299        RESOLVED: No.  The application has already created an image with these
300        flags in Vulkan, so the GL implementation can assume they are valid.
301        Validating this is expensive and unnecessary in almost all applications.
302
303Revision History
304
305    Revision 1, 2020-08-03 (Shahbaz Youssefi)
306        - Initial draft based on EXT_external_objects.
307