KhronosGroup / KhronosGroup/Vulkan-Loader

Better document the intent of instance_extensions and device_extensions in layer manifests

Open
#1,548 0 comments 0 reactions 0 assignees View on GitHub
enhancement layers
Dominant language
C
Stars
695
Forks
343
Avg merge
1d 1h
Merged PRs (30d)
17

Description

> One "device\_extensions" node with an array of one or more elements is required if any device extensions are supported by a layer;

> One "instance_extensions" node with an array of one or more elements is required if any instance extensions are supported by a layer

Both the instance and device extension lists in the JSON manifests specify that layers should "list their supported extensions" without actually defining what supported means.

A rule of thumb I've used is if the layer "implements" the extension, the manifest should contain the extension. That is, if the underlying driver is missing the extension entirely and no other layers implement the extension, the application would still be able to use the extension. Example: On android, VK_EXT_debug_utils is not implemented by the android loader unlike the desktop loader. When the Validation Layer is enabled, because it implements VK_EXT_debug_utils, applications are now able to use the extension.

This is a rule I've had when looking at the manifest, but it isn't the only interpretation used. A survey of existing layers & their extension lists as well as the entrypoints listed should be conducted to see what kinds of extensions are listed and if any similarities in usage is shown.

Lastly, the loader's usage of these manifest fields should be clearly documented so that layer writers can understand what is expected and what it is used for. Currently, the documentation gives no indication for "why" the fields should be populated at all. And if the loader has no practical purpose for the fields, it may be worth pursuing deprecation of the fields.

Contributor guide

Open the contributing guide

Research direction

Survey existing layer manifests, their extension lists, and listed entrypoints, then inspect how the loader uses the instance_extensions and device_extensions fields. Done means the supported-extension rule and the fields' practical purpose are clearly documented for layer writers, or the case for deprecating unused fields is recorded.

Written by the indexing model from the issue text.

Assessment

Tech stack
c
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.