ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

doc: fix GL/VK extension and version checklist to match actual workflow. 

It got written once and never updated, and the order that was there
needed a lot more brain cycles than strictly necessary.
pull/578/head
Vladimír Vondruš 4 years ago
parent
d75adc6872
commit
7d08742341
3 changed files with 122 additions and 53 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 170
      doc/developers.dox
  2. 4
      src/MagnumExternal/OpenGL/GLES2/Emscripten/extensions.txt
  3. 1
      src/MagnumExternal/OpenGL/GLES2/extensions.txt

170
doc/developers.dox
Unescape View File

@ -561,14 +561,41 @@ in inverse --- but usually @ref developers-deprecation "deprecate first".
10. Iterate until the CIs are green
11. Merge to `master`
@section developers-gl-extensions Checklist for adding / removing GL versions and extensions
1. Install [flextGL](https://github.com/mosra/flextgl)
2. Go to `src/MagnumExternal/OpenGL/`:
- Update `GL/extensions.txt`, `GLES2/extensions.txt`,
@section developers-gl-extensions Checklist for adding / removing GL extensions
1. Add new extensions to the GL, GLES and WebGL sections of
`src/Magnum/GL/Extensions.h`
- Order them by extension ID that is mentioned in every extension spec
file. If the extension isn't in the official Khronos registry (such as
various ANGLE extensions), at it at the end of the range.
- Update the numbering to stay monotonic and unique, round up start index
of next section to nearest ten to make the updates bearable
- In case there's a lot of new extensions,
@cpp Implementation::ExtensionCount @ce might needed to be increased.
2. Add them alphabetically ordered to the correct list in
`src/magnum/GL/Context.cpp`
- run GL, ES2, ES3, WebGL1 and WebGL2 build of `GLContextTest` to verify
everything is still okay
- run GL, ES2, ES3, WebGL1 and WebGL2 build of `magnum-gl-info`
- the extension should be listed unless it's not available on given
GL flavor
- and also marked as supported unless the machine doesn't support it
(cross-check with `--extension-strings`)
3. Get [flextGL](https://github.com/mosra/flextgl) and go to
`src/MagnumExternal/OpenGL/`:
- Add/remove extensions in `GL/extensions.txt`, `GLES2/extensions.txt`,
`GLES2/Emscripten/extensions.txt`, `GLES3/extensions.txt`,
`GLES3/Emscripten/extensions.txt` (bump versions or add/remove
extensions)
`GLES3/Emscripten/extensions.txt`, in the same order as in
`src/Magnum/GL/Extensions.h`
- For GLES and WebGL extensions, if they aren't in the official Khronos
registry (such as various ANGLE extensions), check if they're in
ANGLE's [gl_angle_ext.xml](https://raw.githubusercontent.com/google/angle/master/scripts/gl_angle_ext.xml)
at least. If not, like with core WebGL functionality that has no match
in the base GLES spec, you may need to craft your own XML file. See
`src/MagnumExternal/OpenGL/GLES3/webgl.xml` for an example.
- WebGL extensions usually have a GLES extension as a base, but then may
remove certains entrypoints from it. If that's the case, add it to the
function blacklist at the end of the Emscripten-specific files.
- Run `./update-flextgl.sh` to update everything. Reason there is so many
variants of the files are the following:
- Desktop GLES on Windows still links to the ancient `opengl32.dll`
@ -580,11 +607,44 @@ in inverse --- but usually @ref developers-deprecation "deprecate first".
set the function pointers to those exported symbols in case the
system GL header defines them.
- Emscripten doesn't have the ability to manually load extension
pointers, thus it has only header files.
3. Check @cb{.sh} git diff @ce for suspicious changes and whitespace-at-EOL
4. For every new added function, add an entry to `doc/opengl-mapping.dox`
5. For every new added limit query (various `GL_MIN_*` and `GL_MAX_*` macros
etc.), add an entry to the bottom of `doc/opengl-mapping.dox`
pointers either, thus it has only header files.
4. Check @cb{.sh} git diff @ce for suspicious changes and whitespace-at-EOL
- If any extensions don't add any useful symbols, comment them out in
the `extensions.txt` files and regenerate to avoid needless bloat
5. For every new function that appeared in the regenerated extension headers,
add an entry to `doc/opengl-mapping.dox`
6. For every new added limit query that appeared in the regenerated extension
headers (various `GL_MIN_*` and `GL_MAX_*` macros etc.), add an entry to
the bottom of `doc/opengl-mapping.dox`
7. Add new extensions to the general GL, GLES and WebGL lists in
`doc/opengl-support.dox`, again matching the order in `Extensions.h` ---
grouped by prefix, but then ordered by extension number
In order to remove GL functionality, be sure to touch all places mentioned
above, only in inverse --- but usually @ref developers-deprecation "deprecate first",
unless it doesn't affect public API at all.
@see @ref developers-gl-versions, @ref developers-vk-extensions
@section developers-gl-versions Checklist for adding / removing GL versions
1. Add new version enum value:
- to `src/Magnum/GL/Version.h`
- to debug output in `src/Magnum/GL/Version.cpp`
- to @cpp GL::Extension::extensions() @ce in `src/Magnum/GL/Context.cpp`
- to @cpp GL::Context::tryCreate() @ce in `src/Magnum/GL/Context.cpp`
- to specify GLSL version in `src/Magnum/GL/Shader.cpp`
- to the list in `src/Magnum/Platform/gl-info.cpp`
- to the test in `src/Magnum/GL/Test/ContextTest.cpp`
2. Update existing extensions with version in which they became core (last
parameter of the `_extension()` macro in `src/Magnum/GL/Extensions.h`)
3. Go to `src/MagnumExternal/OpenGL/`, bump versions in `GL/extensions.txt`,
`GLES2/extensions.txt`, `GLES2/Emscripten/extensions.txt`,
`GLES3/extensions.txt`, `GLES3/Emscripten/extensions.txt`
4. Continue with @ref developers-gl-extensions for all extensions that were
added by the new version and were not already present
5. For all existing extensions APIs that lose their suffix in the new version,
update doc references to be without the suffix
6. Add a table listing the new version and all new extensions in it to
`doc/opengl-support.dox` (take a list of them from the changelog in the
official spec PDF). Some extensions might be already present in the general
@ -595,31 +655,13 @@ in inverse --- but usually @ref developers-deprecation "deprecate first".
8. Add a new `requires-glXY`, `requires-glesXY` or `requires-webglXY` alias
to `Doxyfile`, `Doxyfile-mcss` and `Doxyfile-public`, copypaste it from
existing and change the numbers
9. Add new version enum value:
- to `src/Magnum/GL/Version.h`
- to debug output in `src/Magnum/GL/Version.cpp`
- to @ref GL::Extension::extensions() in `src/Magnum/GL/Context.cpp`
- to @cpp GL::Context::tryCreate() @ce in `src/Magnum/GL/Context.cpp`
- to specify GLSL version in `src/Magnum/GL/Shader.cpp`
- to the list in `src/Magnum/Platform/gl-info.cpp`
- to the test in `src/Magnum/GL/Test/ContextTest.cpp`
10. Add new extensions to `src/Magnum/GL/Extensions.h`
- order them by extension ID that is mentioned in every extension spec
file
- update the numbering to stay monotonic and unique, round up start index
of next section to nearest ten to make the updates bearable
- in case there's a lot of new extensions, @cpp Implementation::ExtensionCount @ce
might needed to be increased
- run `ContextTest` to verify everything is still okay
11. Update existing extensions with version in which they become core (last
parameter of the `_extension()` macro)
12. Update extension list in `src/magnum/GL/Context.cpp` according to changes
in `src/Magnum/GL/Extensions.h`
In order to remove GL functionality, be sure to touch all places mentioned
above, only in inverse --- but usually @ref developers-deprecation "deprecate first",
unless it doesn't affect public API at all.
@see @ref developers-vk-versions
@section developers-gl-functionality Checklist for adding / removing GL functionality
1. Check if given desktop functionality has equivalent in ES or WebGL, add
@ -728,11 +770,11 @@ In order to remove OpenAL functionality, be sure to touch all places mentioned
above, only in inverse --- but usually @ref developers-deprecation "deprecate first",
unless it doesn't affect public API at all.
@section developers-vk-extensions Checklist for adding / removing Vulkan versions and extensions
@section developers-vk-extensions Checklist for adding / removing Vulkan extensions
1. Add new extensions to `src/Magnum/Vk/Extensions.h`
1. Add new extensions to `src/Magnum/Vk/Extensions.h`
- there's a separate list for instance and device extensions, ensure each
in the right list
is in the right list
- order them by extension ID that is mentioned on every extension spec
page
- update the numbering to stay monotonic and unique, round up start index
@ -743,37 +785,61 @@ unless it doesn't affect public API at all.
need to be increased
2. Add them alphabetically ordered to the correct list in
`src/Magnum/Vk/Extensions.cpp`
3. Update existing extensions with version in which they become core (last
parameter of the `_extension()` macro)
4. Get [flextGL](https://github.com/mosra/flextgl) and go to
- run `VkExtensionsTest` to verify everything is still okay
- run `magnum-vk-info`, the extension should be listed and also marked as
supported, unless the machine doesn't support it (cross-check with
`--extension-strings`)
3. Get [flextGL](https://github.com/mosra/flextgl) and go to
`src/MagnumExternal/Vulkan/`:
- Update `extensions.txt` (bump a version or add/remove extensions),
in the same order as `Extensions.h`
- Add/remove extensions in `extensions.txt`, in the same order as in
`src/Magnum/Vk/Extensions.h`
- Run `./update-flexgl.sh` to update everything
5. Check @cb{.sh} git diff @ce for suspicious changes and whitespace-at-EOL
6. For every new added function and structure, add an entry to
4. Check @cb{.sh} git diff @ce for suspicious changes and whitespace-at-EOL
- If any extensions don't add any useful symbols, comment them out in
the `extensions.txt` file and regenerate to avoid needless bloat
5. For every new added function and structure, add an entry to
`doc/vulkan-mapping.dox`
7. For every new `*Feature` structure, expand the @ref Vk::DeviceFeatures
6. For every new `*Feature` structure, expand the @ref Vk::DeviceFeatures
enum according to @ref developers-vk-features
8. Add a table listing the new version and all new extensions in it to
7. Add new extensions to the general list in `doc/vulkan-support.dox`, again
matching the order in `Extensions.h` --- grouped by prefix, but then
ordered by extension number
In order to remove Vulkan functionality, be sure to touch all places mentioned
above, only in inverse --- but usually @ref developers-deprecation "deprecate first",
unless it doesn't affect public API at all.
@see @ref developers-vk-versions, @ref developers-gl-extensions
@section developers-vk-versions Checklist for adding / removing Vulkan versions
1. Add new version enum value:
- to `src/Magnum/Vk/Version.h`
- to the list in `src/Magnum/Vk/vk-info.cpp`
- to @cpp Vk::InstanceExtension::extensions() @ce and
@cpp Vk::Extension::extensions() @ce in `src/Magnum/Vk/Extensions.cpp`
2. Update existing extensions with version in which they became core (last
parameter of the `_extension()` macro)
3. Continue with @ref developers-vk-extensions for all extensions that were
added by the new version and were not already present
4. For all existing extensions APIs that lose their suffix in the new version,
update doc references to be without the suffix
5. Add a table listing the new version and all new extensions in it to
`doc/vulkan-support.dox` (take a list of them from the changelog in the
official spec PDF). Some extensions might be already present in the general
official spec). Some extensions might be already present in the general
extension list, move them out of there.
9. Add a new `requires-vkXY` page with @c \@m_footernavigation to
6. Add a new `requires-vkXY` page with @c \@m_footernavigation to
`doc/vulkan-support.dox`, mention it as a @c \@subpage at a correct
position in the list
10. Add a new `requires-vkXY` alias to `Doxyfile`, `Doxyfile-mcss` and
7. Add a new `requires-vkXY` alias to `Doxyfile`, `Doxyfile-mcss` and
`Doxyfile-public`, copypaste it from existing and change the numbers
11. Add new version enum value:
- to `src/Magnum/Vk/Version.h`
- to the list in `src/Magnum/Vk/vk-info.cpp`
- to @ref Vk::InstanceExtension::extensions() and
@ref Vk::Extension::extensions() in `src/Magnum/Vk/Extensions.cpp`
In order to remove Vulkan functionality, be sure to touch all places mentioned
above, only in inverse --- but usually @ref developers-deprecation "deprecate first",
unless it doesn't affect public API at all.
@see @ref developers-gl-versions
@section developers-vk-functionality Checklist for adding / removing Vulkan functionality
@todoc adapt from the GL section

4
src/MagnumExternal/OpenGL/GLES2/Emscripten/extensions.txt vendored
Unescape View File

@ -6,6 +6,7 @@ version 2.0 es
extraspec https://raw.githubusercontent.com/google/angle/master/scripts/gl_angle_ext.xml
# WebGL 1 only extensions
extension ANGLE_instanced_arrays optional
extension EXT_color_buffer_half_float optional
extension EXT_sRGB optional
@ -23,6 +24,7 @@ extension OES_fbo_render_mipmap optional
extension ANGLE_depth_texture optional
extension EXT_draw_buffers optional
# WebGL 1 and 2 extensions
extension EXT_texture_filter_anisotropic optional
extension EXT_disjoint_timer_query optional
extension EXT_texture_compression_rgtc optional
@ -36,7 +38,7 @@ extension KHR_texture_compression_astc_ldr optional
# WEBGL_blend_equation_advanced_coherent includes just the enums but not the
# barrier
extension KHR_blend_equation_advanced optional
extension KHR_blend_equation_advanced optional
# From the gl_angle_ext file, base for WEBGL_multi_draw
extension ANGLE_multi_draw optional

1
src/MagnumExternal/OpenGL/GLES2/extensions.txt vendored
Unescape View File

@ -6,6 +6,7 @@ version 2.0 es
extraspec https://raw.githubusercontent.com/google/angle/master/scripts/gl_angle_ext.xml
# ES2-only extensions
extension ANGLE_framebuffer_blit optional
extension ANGLE_framebuffer_multisample optional
extension ANGLE_instanced_arrays optional

Write Preview
Loading…
Cancel
Save