1# Layer Description and Status 2 3## Overview 4 5Layer libraries can be written to intercept or hook VK entry points for various 6debug and validation purposes. One or more VK entry points can be defined in your Layer 7library. Undefined entrypoints in the Layer library will be passed to the next Layer which 8may be the driver. Multiple layer libraries can be chained (actually a hierarchy) together. 9vkEnumerateInstanceLayerProperties and vkEnumerateDeviceLayerProperties can be called to list the 10available layers and their properties. Layers can intercept Vulkan instance level entry points 11in which case they are called an Instance Layer. Layers can intercept device entry points 12in which case they are called a Device Layer. Instance level entry points are those with VkInstance 13or VkPhysicalDevice as first parameter. Device level entry points are those with VkDevice, VkCommandBuffer, 14or VkQueue as the first parameter. Layers that want to intercept both instance and device 15level entrypoints are called Global Layers. vkXXXXGetProcAddr is used internally by the Layers and 16Loader to initialize dispatch tables. Device Layers are activated at vkCreateDevice time. Instance 17Layers are activated at vkCreateInstance time. Layers can also be activated via environment variables 18(VK_INSTANCE_LAYERS or VK_DEVICE_LAYERS). 19 20All validation layers work with the DEBUG_REPORT extension to provide the application or user with 21validation feedback. When a validation layer is enabled, it will look at the vk_layer_settings.txt 22file to determine its behavior. Such as outputing to a file, stdout or debug output (Windows). An 23application can also register callback functions via the DEBUG_REPORT extension to receive callbacks 24when the requested validation events happen. Application callbacks happen regardless of the 25settings in vk_layer_settings.txt 26 27### Layer library example code 28 29Note that some layers are code-generated and will therefore exist in the directory (build_dir)/layers 30 31-include/vkLayer.h - header file for layer code. 32 33### Layer Details 34For complete details of current validation layers, including all of the validation checks that they perform, please refer to the document layers/vk_validation_layer_details.md. Below is a brief overview of each layer. 35 36### Standard Validation 37This is a meta-layer managed by the loader. (name = VK_LAYER_LUNARG_standard_validation) - specifying this layer name will cause the loader to load the all of the standard validation layers (listed below) in the following optimal order: VK_LAYER_GOOGLE_threading, VK_LAYER_LUNARG_parameter_validation, VK_LAYER_LUNARG_device_limits, VK_LAYER_LUNARG_object_tracker, VK_LAYER_LUNARG_image, VK_LAYER_LUNARG_core_validation, VK_LAYER_LUNARG_swapchain, and VK_LAYER_GOOGLE_unique_objects. Other layers can be specified and the loader will remove duplicates. 38 39### Print Object Stats 40(build dir)/layers/object_tracker.cpp (name=VK_LAYER_LUNARG_object_tracker) - Track object creation, use, and destruction. As objects are created, they're stored in a map. As objects are used, the layer verifies they exist in the map, flagging errors for unknown objects. As objects are destroyed, they're removed from the map. At vkDestroyDevice() and vkDestroyInstance() times, if any objects have not been destroyed, they are reported as leaked objects. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout. 41 42### Validate API State and Shaders 43layers/core\_validation.cpp (name=VK\_LAYER\_LUNARG\_core\_validation) - The core\_validation layer does the bulk of the API validation that requires storing state. Some of the state it tracks includes the Descriptor Set, Pipeline State, Shaders, and dynamic state, and memory objects and bindings. It performs some point validation as states are created and used, and further validation Draw call and QueueSubmit time. Of primary interest is making sure that the resources bound to Descriptor Sets correctly align with the layout specified for the Set. Also, all of the image and buffer layouts are validated to make sure explicit layout transitions are properly managed. Related to memory, core\_validation includes tracking object bindings, memory hazards, and memory object lifetimes. It also validates several other hazard-related issues related to command buffers, fences, and memory mapping. Additionally core\_validation include shader validation (formerly separate shader\_checker layer) that inspects the SPIR-V shader images and fixed function pipeline stages at PSO creation time. It flags errors when inconsistencies are found across interfaces between shader stages. The exact behavior of the checks depends on the pair of pipeline stages involved. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout. 44 45### Check parameters 46layers/parameter_validation.cpp (name=VK_LAYER_LUNARG_parameter_validation) - Check the input parameters to API calls for validity. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout. 47 48### Image parameters 49layers/image.cpp (name=VK_LAYER_LUNARG_image) - The image layer is intended to validate image parameters, formats, and correct use. Images are a significant enough area that they were given a separate layer. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout. 50 51### Check threading 52layers/threading.cpp (name=VK_LAYER_GOOGLE_threading) - Check multithreading of API calls for validity. Currently this checks that only one thread at a time uses an object in free-threaded API calls. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout. 53 54### Swapchain 55layers/swapchain.cpp (name=VK_LAYER_LUNARG_swapchain) - Check that WSI extensions are being used correctly. 56 57### Device Limitations 58layers/device_limits.cpp (name=VK_LAYER_LUNARG_device_limits) - This layer is intended to capture underlying device features and limitations and then flag errors if an app makes requests for unsupported features or exceeding limitations. This layer is a work in progress and currently only flags some high-level errors without flagging errors on specific feature and limitation. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout. 59 60### Unique Objects 61(build dir)/layers/unique_objects.cpp (name=VK_LAYER_GOOGLE_unique_objects) - The Vulkan specification allows objects that have non-unique handles. This makes tracking object lifetimes difficult in that it is unclear which object is being referenced on deletion. The unique_objects layer was created to address this problem. If loaded in the correct position (last, which is closest to the display driver) it will wrap all objects with a unique object representation, allowing proper object lifetime tracking. This layer does no validation on its own, and may not be required for the proper operation of all layers or all platforms. One sign that it is needed is the appearance of errors emitted from the object_tracker layer indicating the use of previously destroyed objects. 62 63## Using Layers 64 651. Build VK loader using normal steps (cmake and make) 662. Place libVkLayer_<name>.so in the same directory as your VK test or app: 67 68 cp build/layer/libVkLayer_threading.so build/tests 69 70 This is required for the Loader to be able to scan and enumerate your library. 71 Alternatively, use the VK\_LAYER\_PATH environment variable to specify where the layer libraries reside. 72 733. Create a vk_layer_settings.txt file in the same directory to specify how your layers should behave. 74 75 Model it after the following example: [*vk_layer_settings.txt*](vk_layer_settings.txt) 76 774. Specify which Layers to activate by using 78vkCreateDevice and/or vkCreateInstance or environment variables. 79 80 export VK\_INSTANCE\_LAYERS=VK\_LAYER\_LUNARG\_param\_checker:VK\_LAYER\_LUNARG\_core\_validation 81 export VK\_DEVICE\_LAYERS=VK\_LAYER\_LUNARG\_param\_checker:VK\_LAYER\_LUNARG\_core\_validation 82 cd build/tests; ./vkinfo 83 84 85## Status 86 87 88### Current known issues 89 90