From cefe71484b2840f4e4d3448340162121d726e252 Mon Sep 17 00:00:00 2001 From: Courtney Goeltzenleuchter Date: Mon, 28 Sep 2015 15:13:45 -0600 Subject: sdk: Update release notes for 0.9 SDK --- README.md | 44 +++++++++++++++----------------------------- layers/README.md | 33 ++++++++++++++++++++++++++------- 2 files changed, 41 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 20d94e86..d65dc8d6 100755 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # Explicit GL (VK) Ecosystem Components -*Version 0.8, 04 Feb 2015* +*Version 0.9, 28 Sep 2015* This project provides *open source* tools for VK Developers. @@ -21,11 +21,9 @@ demos for GDC. The following components are available: - VK Library and header files, which include: - [*ICD Loader*](loader) and [*Layer Manager*](layers/README.md) - - Snapshot of *VK* and *BIL* header files from [*Khronos*](www.khronos.org) + - Snapshot of *VK* and *SPIR-V* header files from [*Khronos*](www.khronos.org) -- [*VKTRACE tools*](tools/vktrace) - - ![ScreenShot](docs/images/Vktrace-Small.png) +- [*VKTRACE tools*](vktrace) - Core [*Validation Layers*](layers/) @@ -33,34 +31,19 @@ The following components are available: ## New -- Updated loader, driver, demos, tests and many tools to use "alpha" vulkan.h (~ version 47). - Supports new resource binding model, memory allocation, pixel FORMATs and - other updates. - APIDump layer is working with these new API elements. - VkTrace can trace and replay the cube and tri demos. - Other layers in progress. -- Warning: Recent versions of ubuntu 14.10 have **REMOVED** DRI 3. +- Header matches provisional specification (v170) with two changes. + - DrawIndirect correction (bug #14715) + - DynamicState refactor (bug #14365) +- Provisional specification document (PDF & HTML) +- Loader now uses JSON manifest files for ICDs and layers. See BUILD.md for details on customizing loader behavior. +- All validation errors now reported via DEBUG_REPORT extension. [*DEBUG_REPORT*, Extension Document](TODO: link to VulkanDbgExtensions.docx) +- Warning: The sample driver requires DRI3 and recent versions of ubuntu 14.10 have **REMOVED** DRI 3. Version: 2:2.99.914-1~exp1ubuntu4.1 is known to work. Ubuntu 15.04 requires customization to add DRI3. See BUILD.md for details. ## Prior updates -- VK API trace and capture tools. See tools/vktrace/README.md for details. -- Sample driver now supports multiple render targets. Added TriangleMRT to test that functionality. -- Added VK_SLOT_SHADER_TEXTURE_RESOURCE to vulkan.h as a descriptor slot type to work around confusion in GLSL - between textures and buffers as shader resources. -- Misc. fixes for layers and Intel sample driver -- Added mutex to APIDump, APIDumpFile and DrawState to prevent apparent threading issues using printf -- Fix support for {Fill,Copy}Memory -- MemTracker can report issues to application via debug callback -- Update test infrastructure to improve ease of writing new tests. Add image comparison feature for regression testing. Requires ImageMagick library. -- Misc. fixes to demos, layers and Intel sample driver -- Added mutex to APIDump, APIDumpFile and DrawState to prevent apparent threading issues using printf -- Fix support for {Fill,Copy}Memory -- MemTracker can report issues to application via debug callback -- Update test infrastructure to improve ease of writing new tests. Add image comparison feature for regression testing. Requires ImageMagick library. -- Misc. fixes to demos, layers and Intel sample driver ## How to Build and Run @@ -72,8 +55,11 @@ Information on how to enable the various Debug and Validation layers is in ## References This version of the components are written based on the following preliminary specs and proposals: -- [**VK Programers Reference**, 1 Jul 2014](https://cvs.khronos.org/svn/repos/oglc/trunk/nextgen/proposals/AMD/Explicit%20GL%20Programming%20Guide%20and%20API%20Reference.pdf) -- [**BIL**, revision 29](https://cvs.khronos.org/svn/repos/oglc/trunk/nextgen/proposals/BIL/Specification/BIL.html) +- [**Core Vulkan Header**, vulkan.h](https://gitlab.khronos.org/vulkan/vulkan/blob/6e1463d85b747fcad43c48eb8abd94d0f58824de/src/include/vulkan.h) +- [**SPIR-V**, revision 32](https://cvs.khronos.org/svn/repos/SPIRV/trunk/Promoter32) +- [**WSI Device Swapchain**, Revision 53 for VK_EXT_KHR_device_swapchain](https://cvs.khronos.org/svn/repos/promoters/specs/candidates/oglc/extensions/20150910/vk_ext_khr_device_swapchain.txt) +- [**WSI Swapchain**, Revision 17 for VK_EXT_KHR_swapchain](https://cvs.khronos.org/svn/repos/promoters/specs/candidates/oglc/extensions/20150910/vk_ext_khr_swapchain.txt) + ## License This work is intended to be released as open source under a BSD-style diff --git a/layers/README.md b/layers/README.md index 2dabf4a7..c87629a9 100644 --- a/layers/README.md +++ b/layers/README.md @@ -17,6 +17,13 @@ Loader to initialize dispatch tables. Device Layers are activated at vkCreateDev Layers are activated at vkCreateInstance. Layers can also be activated via environment variables (VK_INSTANCE_LAYERS or VK_DEVICE_LAYERS). +All validation layers work with the DEBUG_REPORT extension to provide the application or user with +validation feedback. When a validation layer is enabled, it will look at the vk_layer_settings.txt +file to determine it's behavior. Such as outputing to a file, stdout or debug output (Windows). An +application can also register callback functions via the DEBUG_REPORT extension to receive callbacks +when the requested validation events happen. Application callbacks happen regardless of the +settings in vk_layer_settings.txt + ##Layer library example code Note that some layers are code-generated and will therefore exist in the directory (build_dir)/layers @@ -31,25 +38,37 @@ layer/Basic.cpp (name=Basic) simple example wrapping a few entrypoints. Shows la layer/Multi.cpp (name=multi1:multi2) simple example showing multiple layers per library -(build dir)/layer/generic_layer.c (name=Generic) - auto generated example wrapping all VK entrypoints. +(build dir)/layer/generic_layer.cpp (name=Generic) - auto generated example wrapping all VK entrypoints. ### Print API Calls and Parameter Values (build dir)/layer/api_dump.cpp (name=APIDump) - print out API calls along with parameter values ### Print Object Stats -(build dir>/layer/object_track.c (name=ObjectTracker) - Print object CREATE/USE/DESTROY stats. Individually track objects by category. VkObjectType enum defined in vulkan.h. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout. Provides custom interface to query number about the total number of objects or of live objects of given type. To get information on all objects, use "VK\_UINT64 objTrackGetObjectsCount()" and the secondary call to return an array of those objects "VK\_RESULT objTrackGetObjects(VK\_UINT64 objCount, OBJTRACK\_NODE\* pObjNodeArray)". For objects of a specific type, use "VK\_UINT64 objTrackGetObjectsOfTypeCount(VkObjectType type)" and the secondary call to return an array of those objects "VK\_RESULT objTrackGetObjectsOfType(VK\_OBJECT\_TYPE type, VK\_UINT64 objCount, OBJTRACK\_NODE\* pObjNodeArray)". +(build dir)/layer/object_track.cpp (name=ObjectTracker) - Track object CREATE/USE/DESTROY stats. Individually track objects by category. VkObjectType enum defined in vulkan.h. ### Report Draw State -layer/draw\_state.c (name=DrawState) - DrawState reports the Descriptor Set, Pipeline State, and dynamic state at each Draw call. DrawState layer performs a number of validation checks on this state. Of primary interest is making sure that the resources bound to Descriptor Sets correctly align with the layout specified for the Set. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout. +layer/draw\_state.cpp (name=DrawState) - DrawState reports the Descriptor Set, Pipeline State, and dynamic state at each Draw call. DrawState layer performs a number of validation checks on this state. Of primary interest is making sure that the resources bound to Descriptor Sets correctly align with the layout specified for the Set. ### Track GPU Memory -layer/mem\_tracker.c (name=MemTracker) - MemTracker functions mostly as a validation layer, attempting to ensure that memory objects are managed correctly by the application. These memory objects are bound to pipelines, objects, and command buffers, and then submitted to the GPU for work. As an example, the layer validates that the correct memory objects have been bound, and that they are specified correctly when the command buffers are submitted. Also, that only existing memory objects are referenced, and that any destroyed memory objects are not referenced. Another type of validation done is that before any memory objects are reused or destroyed, the layer ensures that the application has confirmed that they are no longer in use, and that they have been properly unbound before destruction. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout. +layer/mem\_tracker.cpp (name=MemTracker) - MemTracker functions mostly as a validation layer, attempting to ensure that memory objects are managed correctly by the application. These memory objects are bound to pipelines, objects, and command buffers, and then submitted to the GPU for work. As an example, the layer validates that the correct memory objects have been bound, and that they are specified correctly when the command buffers are submitted. Also, that only existing memory objects are referenced, and that any destroyed memory objects are not referenced. Another type of validation done is that before any memory objects are reused or destroyed, the layer ensures that the application has confirmed that they are no longer in use, and that they have been properly unbound before destruction. + +### Device Limits +/layer/device_limits.cpp (name=DeviceLimits) - Check that parameters used do not exceed device limits. ### Check parameters -/layer/param_checker.c (name=ParamChecker) - Check the input parameters to API calls for validity. Currently this only checks ENUM params directly passed to API calls and ENUMs embedded in struct params. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout. +/layer/param_checker.cpp (name=ParamChecker) - Check the input parameters to API calls for validity. Currently this only checks ENUM params directly passed to API calls and ENUMs embedded in struct params. + +### Image Checker +/layer/image.cpp (name=Image) - Verify parameters on Vulkan calls that use VkImage. ### Check threading -/layer/threading.c (name=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. +/layer/threading.cpp (name=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. + +### Swapchain +/layer/swapchain.cpp (name=Swapchain) - Check that WSI extensions are being used correctly. + +### Shader Checker +/layer/shader_checker.cpp (name=ShaderChecker) - Verify SPIR-V shader layout matches descriptor set. ## Using Layers @@ -59,7 +78,7 @@ layer/mem\_tracker.c (name=MemTracker) - MemTracker functions mostly as a valida cp build/layer/libVKLayerBasic.so build/layer/libVKLayerGeneric.so build/tests This is required for the Loader to be able to scan and enumerate your library. - Alternatively, use the VK\_LAYER\_DIRS (VK\_LAYER\_FOLDERS Windows) environment variable to specify where the layer libraries reside. + Alternatively, use the VK\_LAYER\_PATH environment variable to specify where the layer libraries reside. 3. Specify which Layers to activate by using vkCreateDevice and/or vkCreateInstance or environment variables. -- cgit v1.2.3