From 4f7b9d7b83d91fa5fbb998a7968aaed509b8bd84 Mon Sep 17 00:00:00 2001 From: Petr Kraus Date: Mon, 3 Dec 2018 11:00:14 +0100 Subject: [PATCH] Random editing of ray tracing chapter (#860) * Typo, markup, format editing in ray tracing chapters * Fix Terminology in ray tracing chapters * Fix some VUs in ray tracing chapters --- appendices/VK_NV_ray_tracing.txt | 12 +- .../raytracing-descriptors.txt | 8 +- .../raytracing-pipelines.txt | 49 ++--- .../raytracing-resources.txt | 201 ++++++++---------- .../VK_NV_ray_tracing/raytracing-shaders.txt | 28 +-- chapters/VK_NV_ray_tracing/raytracing.txt | 175 +++++++-------- chapters/drawing.txt | 4 +- 7 files changed, 225 insertions(+), 252 deletions(-) diff --git a/appendices/VK_NV_ray_tracing.txt b/appendices/VK_NV_ray_tracing.txt index 58bf8d92..2d23dd19 100644 --- a/appendices/VK_NV_ray_tracing.txt +++ b/appendices/VK_NV_ray_tracing.txt @@ -43,7 +43,7 @@ functionality: This extension adds support for the following SPIR-V extension in Vulkan: - * +SPV_NV_ray_tracing+ + * `SPV_NV_ray_tracing` === New Object Types @@ -77,16 +77,16 @@ This extension adds support for the following SPIR-V extension in Vulkan: ** ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV * Extending elink:VkPipelineBindPoint: ** ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV - * Extending elink:VkDescriptorType + * Extending elink:VkDescriptorType: ** ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV - * Extending elink:VkAccessFlagBits + * Extending elink:VkAccessFlagBits: ** ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_NV ** ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_NV - * Extending elink:VkQueryType + * Extending elink:VkQueryType: ** ename:VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV - * Extending elink:VkPipelineCreateFlagBits + * Extending elink:VkPipelineCreateFlagBits: ** ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV - * Extending elink:VkIndexType + * Extending elink:VkIndexType: ** ename:VK_INDEX_TYPE_NONE_NV === New Enums diff --git a/chapters/VK_NV_ray_tracing/raytracing-descriptors.txt b/chapters/VK_NV_ray_tracing/raytracing-descriptors.txt index 9a6fa43f..ffa92176 100644 --- a/chapters/VK_NV_ray_tracing/raytracing-descriptors.txt +++ b/chapters/VK_NV_ray_tracing/raytracing-descriptors.txt @@ -19,14 +19,14 @@ include::../../api/structs/VkWriteDescriptorSetAccelerationStructureNV.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:accelerationStructureCount is the number of elements in - pAccelerationStructures - * pname:pAccelerationStructures are the acceleration structures to update + pname:pAccelerationStructures. + * pname:pAccelerationStructures are the acceleration structures to update. .Valid Usage **** * [[VUID-VkWriteDescriptorSetAccelerationStructureNV-accelerationStructureCount-02236]] - pname:accelerationStructureCount must: be equal to descriptorCount in - the extended structure. + pname:accelerationStructureCount must: be equal to pname:descriptorCount + in the extended structure **** include::../../validity/structs/VkWriteDescriptorSetAccelerationStructureNV.txt[] diff --git a/chapters/VK_NV_ray_tracing/raytracing-pipelines.txt b/chapters/VK_NV_ray_tracing/raytracing-pipelines.txt index 66842846..3524978e 100644 --- a/chapters/VK_NV_ray_tracing/raytracing-pipelines.txt +++ b/chapters/VK_NV_ray_tracing/raytracing-pipelines.txt @@ -16,7 +16,7 @@ include::../../api/protos/vkCreateRayTracingPipelinesNV.txt[] * pname:device is the logical device that creates the ray tracing pipelines. * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that - pipeline caching is disabled; or the handle of a valid + pipeline caching is disabled, or the handle of a valid <> object, in which case use of that cache is enabled for the duration of the command. * pname:createInfoCount is the length of the pname:pCreateInfos and @@ -25,8 +25,8 @@ include::../../api/protos/vkCreateRayTracingPipelinesNV.txt[] structures. * pname:pAllocator controls host memory allocation as described in the <> chapter. - * pname:pPipelines is a pointer to an array in which the resulting compute - pipeline objects are returned. + * pname:pPipelines is a pointer to an array in which the resulting ray + tracing pipeline objects are returned. .Valid Usage **** @@ -82,7 +82,7 @@ Derivatives>>. **** * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02404]] If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT - flag, and pname:basePipelineIndex is -1, pname:basePipelineHandle must: + flag, and pname:basePipelineIndex is `-1`, pname:basePipelineHandle must: be a valid handle to a ray tracing sname:VkPipeline * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02405]] If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT @@ -91,12 +91,12 @@ Derivatives>>. command's pname:pCreateInfos parameter * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02406]] If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT - flag, and pname:basePipelineIndex is not -1, pname:basePipelineHandle + flag, and pname:basePipelineIndex is not `-1`, pname:basePipelineHandle must: be dlink:VK_NULL_HANDLE * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02407]] If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and pname:basePipelineHandle is not dlink:VK_NULL_HANDLE, - pname:basePipelineIndex must: be -1 + pname:basePipelineIndex must: be `-1` * [[VUID-VkRayTracingPipelineCreateInfoNV-stage-02408]] The pname:stage member of one element of pname:pStages must: be ename:VK_SHADER_STAGE_RAYGEN_BIT_NV @@ -112,10 +112,10 @@ Derivatives>>. * [[VUID-VkRayTracingPipelineCreateInfoNV-layout-02411]] The number of resources in pname:layout accessible to each shader stage that is used by the pipeline must: be less than or equal to - sname:VkPhysicalDeviceLimits::pname:maxPerStageResources + slink:VkPhysicalDeviceLimits::pname:maxPerStageResources * [[VUID-VkRayTracingPipelineCreateInfoNV-maxRecursionDepth-02412]] pname:maxRecursionDepth must: be less than or equal to - VkPhysicalDeviceRayTracingPropertiesNV::pname:maxRecursionDepth + slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxRecursionDepth **** include::../../validity/structs/VkRayTracingPipelineCreateInfoNV.txt[] @@ -162,28 +162,28 @@ include::../../api/structs/VkRayTracingShaderGroupCreateInfoNV.txt[] pname:generalShader must: be a valid index into pname:pStages referring to a shader of ename:VK_SHADER_STAGE_RAYGEN_BIT_NV, ename:VK_SHADER_STAGE_MISS_BIT_NV, or - ename:VK_SHADER_STAGE_CALLABLE_BIT_NV. + ename:VK_SHADER_STAGE_CALLABLE_BIT_NV * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02414]] If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then pname:closestHitShader, pname:anyHitShader, and pname:intersectionShader - must: be ename:VK_SHADER_UNUSED_NV. + must: be ename:VK_SHADER_UNUSED_NV * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02415]] If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV then pname:intersectionShader must: be a valid index into pname:pStages - referring to a shader of ename:VK_SHADER_STAGE_INTERSECTION_BIT_NV. + referring to a shader of ename:VK_SHADER_STAGE_INTERSECTION_BIT_NV * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02416]] If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV then - pname:intersectionShader must: be ename:VK_SHADER_UNUSED_NV. + pname:intersectionShader must: be ename:VK_SHADER_UNUSED_NV * [[VUID-VkRayTracingShaderGroupCreateInfoNV-closestHitShader-02417]] pname:closestHitShader must: be either ename:VK_SHADER_UNUSED_NV or a valid index into pname:pStages referring to a shader of - ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV. + ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV * [[VUID-VkRayTracingShaderGroupCreateInfoNV-anyHitShader-02418]] pname:anyHitShader must: be either ename:VK_SHADER_UNUSED_NV or a valid index into pname:pStages referring to a shader of - ename:VK_SHADER_STAGE_ANY_HIT_BIT_NV. + ename:VK_SHADER_STAGE_ANY_HIT_BIT_NV **** include::../../validity/structs/VkRayTracingShaderGroupCreateInfoNV.txt[] @@ -194,20 +194,20 @@ include::../../validity/structs/VkRayTracingShaderGroupCreateInfoNV.txt[] -- Possible values of pname:type in sname:VkRayTracingShaderGroupCreateInfoNV -are:, +are: include::../../api/enums/VkRayTracingShaderGroupTypeNV.txt[] * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV indicates a shader group with a single ename:VK_SHADER_STAGE_RAYGEN_BIT_NV, ename:VK_SHADER_STAGE_MISS_BIT_NV, or - ename:VK_SHADER_STAGE_CALLABLE_BIT_NV shader in it + ename:VK_SHADER_STAGE_CALLABLE_BIT_NV shader in it. * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV specifies a shader group that only hits triangles and must: not contain an - intersection shader, only closest hit and any hit. + intersection shader, only closest hit and any-hit. * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV specifies a shader group that only intersects with custom geometry and must: - contain an intersection shader and may: contain closest hit and any hit + contain an intersection shader and may: contain closest hit and any-hit shaders. [NOTE] @@ -215,7 +215,7 @@ include::../../api/enums/VkRayTracingShaderGroupTypeNV.txt[] ==== For current group types, the hit group type could be inferred from the presence or absence of the intersection shader, but we provide the type -explicitly for future hit groups that don't have that property. +explicitly for future hit groups that do not have that property. ==== -- @@ -234,7 +234,8 @@ include::../../api/protos/vkGetRayTracingShaderGroupHandlesNV.txt[] * pname:firstGroup is the index of the first group to retrieve a handle for from the sname:VkPipelineShaderStageCreateInfo::pname:pGroups array. * pname:groupCount is the number of shader handles to retrieve. - * pname:dataSize is the size in bytes of the buffer pointed to by pData. + * pname:dataSize is the size in bytes of the buffer pointed to by + pname:pData. * pname:pData is a pointer to a user-allocated buffer where the results will be written. @@ -252,9 +253,9 @@ include::../../api/protos/vkGetRayTracingShaderGroupHandlesNV.txt[] include::../../validity/protos/vkGetRayTracingShaderGroupHandlesNV.txt[] -- -Ray tracing pipelines can contain more shaders than a graphics or compute +Ray tracing pipelines can: contain more shaders than a graphics or compute pipeline, so to allow parallel compilation of shaders within a pipeline, an -application may: choose to defer compilation until a later point in time. +application can: choose to defer compilation until a later point in time. [open,refpage='vkCompileDeferredNV',desc='Deferred compilation of shaders',type='protos'] -- @@ -273,9 +274,9 @@ include::../../api/protos/vkCompileDeferredNV.txt[] **** * [[VUID-vkCompileDeferredNV-pipeline-02237]] pname:pipeline must: have been created with - ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV. + ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV * [[VUID-vkCompileDeferredNV-shader-02238]] - pname:shader must: not have been called as a deferred compile before. + pname:shader must: not have been called as a deferred compile before **** include::../../validity/protos/vkCompileDeferredNV.txt[] diff --git a/chapters/VK_NV_ray_tracing/raytracing-resources.txt b/chapters/VK_NV_ray_tracing/raytracing-resources.txt index c53e920a..a07b9f94 100644 --- a/chapters/VK_NV_ray_tracing/raytracing-resources.txt +++ b/chapters/VK_NV_ray_tracing/raytracing-resources.txt @@ -6,7 +6,7 @@ [open,refpage='VkAccelerationStructureNV',desc='Opaque handle to an acceleration structure object',type='handles'] -- -Acceleration structures are an opaque structure that can be built by the +Acceleration structures are an opaque structure that is built by the implementation to more efficiently perform spatial queries on the provided geometric data. For this extension, an acceleration structure is either a top-level @@ -44,12 +44,12 @@ include::../../api/protos/vkCreateAccelerationStructureNV.txt[] handle in which the resulting acceleration structure object is returned. Similar to other objects in Vulkan, the acceleration structure creation -merely creates an object with a specific "shape" as specified by the -information in sname:VkAccelerationStructureInfoNV and pname:compactedSize +merely creates an object with a specific "`shape`" as specified by the +information in slink:VkAccelerationStructureInfoNV and pname:compactedSize in pname:pCreateInfo. Populating the data in the object after allocating and binding memory is -done with fname:vkCmdBuildAccelerationStructureNV and -fname:vkCmdCopyAccelerationStructureNV. +done with flink:vkCmdBuildAccelerationStructureNV and +flink:vkCmdCopyAccelerationStructureNV. Acceleration structure creation uses the count and type information from the geometries, but does not use the data references in the structures. @@ -67,16 +67,16 @@ include::../../api/structs/VkAccelerationStructureCreateInfoNV.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:compactedSize is the size from the result of - flink:vkCmdWriteAccelerationStructuresPropertiesNV, if this acceleration + flink:vkCmdWriteAccelerationStructuresPropertiesNV if this acceleration structure is going to be the target of a compacting copy. - * pname:info contains the slink:VkAccelerationStructureInfoNV information - for the acceleration structure's parameters + * pname:info is the slink:VkAccelerationStructureInfoNV structure that + specifies further parameters of the created acceleration structure. .Valid Usage **** * [[VUID-VkAccelerationStructureCreateInfoNV-compactedSize-02421]] If pname:compactedSize is not `0` then both - pname:info::pname:geometryCount and pname:info::pname:instanceCount + pname:info.geometryCount and pname:info.instanceCount must: be `0` **** @@ -97,40 +97,40 @@ include::../../api/structs/VkAccelerationStructureInfoNV.txt[] * pname:flags is a bitmask of elink:VkBuildAccelerationStructureFlagBitsNV specifying additional parameters of the acceleration structure. * pname:instanceCount specifies the number of instances that will be in - the new acceleration structure + the new acceleration structure. * pname:geometryCount specifies the number of geometries that will be in - the new acceleration structure - * pname:pGeometries is an array of slink:VkGeometryNV structures which + the new acceleration structure. + * pname:pGeometries is an array of slink:VkGeometryNV structures, which contain the scene data being passed into the acceleration structure. -sname:VkAccelerationStructureInfoNV contains information that's used both +sname:VkAccelerationStructureInfoNV contains information that is used both for acceleration structure creation with fname:vkCreateAccelerationStructureNV and in combination with the actual geometric data to build the acceleration structure with -fname:vkCmdBuildAccelerationStructureNV. +flink:vkCmdBuildAccelerationStructureNV. .Valid Usage **** * [[VUID-VkAccelerationStructureInfoNV-geometryCount-02422]] pname:geometryCount must: be less than or equal to - sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount + slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount * [[VUID-VkAccelerationStructureInfoNV-instanceCount-02423]] pname:instanceCount must: be less than or equal to - sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxInstanceCount + slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxInstanceCount * [[VUID-VkAccelerationStructureInfoNV-maxTriangleCount-02424]] The total number of triangles in all geometries must: be less than or equal to - sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxTriangleCount + slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxTriangleCount * [[VUID-VkAccelerationStructureInfoNV-type-02425]] If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV then - pname:geometryCount must: be `0`. + pname:geometryCount must: be `0` * [[VUID-VkAccelerationStructureInfoNV-type-02426]] If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV - then pname:instanceCount must: be `0`. - * [[VUID-VkAccelerationStructureInfoNV-compactedSize-02427]] - If pname:compactedSize is not `0` then both pname:geometryCount and - pname:instanceCount must: be `0` - + then pname:instanceCount must: be `0` + * If pname:flags has the + ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV bit set, + then it must: not have the + ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV bit set **** include::../../validity/structs/VkAccelerationStructureInfoNV.txt[] @@ -141,16 +141,16 @@ include::../../validity/structs/VkAccelerationStructureInfoNV.txt[] -- Values which can: be set in slink:VkAccelerationStructureInfoNV::pname:type, -specifying specifying the type of acceleration structure, are: +specifying the type of acceleration structure, are: include::../../api/enums/VkAccelerationStructureTypeNV.txt[] - * ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV is a bottom-level - acceleration structure containing the AABBs or geometry to be - intersected. * ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV is a top-level acceleration structure containing instance data referring to bottom-level level acceleration structures. + * ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV is a bottom-level + acceleration structure containing the AABBs or geometry to be + intersected. -- @@ -163,36 +163,30 @@ specifying additional parameters for acceleration structure builds, are: include::../../api/enums/VkBuildAccelerationStructureFlagBitsNV.txt[] * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV indicates that - the specified acceleration structure may: be updated with pname:update - of true in flink:vkCmdBuildAccelerationStructureNV. - This flag must: only be set on a build that is not an update or is an - update with a source that also had this flag set. + the specified acceleration structure can: be updated with pname:update + of ename:VK_TRUE in flink:vkCmdBuildAccelerationStructureNV. * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV indicates - that the specified acceleration structure may: act as the source for + that the specified acceleration structure can: act as the source for flink:vkCmdCopyAccelerationStructureNV with pname:mode of ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV to produce a compacted acceleration structure. * ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV indicates - that the given acceleration structure build should prioritize trace + that the given acceleration structure build should: prioritize trace performance over build time. * ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV indicates - that the given acceleration structure build should prioritize build time - over trace performance. + that the given acceleration structure build should: prioritize build + time over trace performance. * ename:VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_NV indicates that - this acceleration structure should minimize the size of scratch memory - and final result build, potentially at the expense of build time or - trace performance. - -ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV and -ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV must: not be -used in the same flags. + this acceleration structure should: minimize the size of the scratch + memory and the final result build, potentially at the expense of build + time or trace performance. [NOTE] .Note ==== ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV and ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV may: take more -time and memory than a normal build, so should only be used when those +time and memory than a normal build, and so should: only be used when those features are used. ==== -- @@ -214,8 +208,8 @@ include::../../api/structs/VkGeometryNV.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:geometryType describes which type of geometry this VkGeometryNV - refers to. + * pname:geometryType describes which type of geometry this + sname:VkGeometryNV refers to. * pname:geometry contains the geometry data as described in slink:VkGeometryDataNV. * pname:flags has flags describing options for this geometry. @@ -231,9 +225,9 @@ Geometry types are specified by elink:VkGeometryTypeNV, which takes values: include::../../api/enums/VkGeometryTypeNV.txt[] * ename:VK_GEOMETRY_TYPE_TRIANGLES_NV indicates that the pname:triangles - of sname:VkGeometryDataNV contains valid data. + of slink:VkGeometryDataNV contains valid data. * ename:VK_GEOMETRY_TYPE_AABBS_NV indicates that the pname:aabbs of - sname:VkGeometryDataNV contains valid data. + slink:VkGeometryDataNV contains valid data. -- [open,refpage='VkGeometryFlagBitsNV',desc='Bitmask specifying additional parameters for a geometry',type='enums'] @@ -245,11 +239,11 @@ additional parameters for acceleration structure builds, are: include::../../api/enums/VkGeometryFlagBitsNV.txt[] * ename:VK_GEOMETRY_OPAQUE_BIT_NV indicates that this geometry does not - invoke any-hit shaders even if present in a hit group. + invoke the any-hit shaders even if present in a hit group. * ename:VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_NV indicates that - the implementation must: only call any hit a single time for each - primitive in this geometry. - If this bit is absent an implementation may: invoke an any hit shader + the implementation must: only call the any-hit shader a single time for + each primitive in this geometry. + If this bit is absent an implementation may: invoke the any-hit shader more than once for this geometry. -- @@ -269,10 +263,12 @@ The sname:VkGeometryDataNV structure is defined as: include::../../api/structs/VkGeometryDataNV.txt[] - * pname:triangles contains triangle data if pname:geometryType is + * pname:triangles contains triangle data if + sname:VkGeometryNV::pname:geometryType is ename:VK_GEOMETRY_TYPE_TRIANGLES_NV. * pname:aabbs contains axis-aligned bounding box data if - pname:geometryType is ename:VK_GEOMETRY_TYPE_AABBS_NV. + sname:VkGeometryNV::pname:geometryType is + ename:VK_GEOMETRY_TYPE_AABBS_NV. include::../../validity/structs/VkGeometryDataNV.txt[] -- @@ -314,7 +310,7 @@ pname:indexCount. pname:vertexOffset must: be less than the size of pname:vertexData * [[VUID-VkGeometryTrianglesNV-vertexOffset-02429]] pname:vertexOffset must: be a multiple of the component size of - pname:vertexFormat. + pname:vertexFormat * [[VUID-VkGeometryTrianglesNV-vertexFormat-02430]] pname:vertexFormat must: be one of ename:VK_FORMAT_R32G32B32_SFLOAT, ename:VK_FORMAT_R32G32_SFLOAT, ename:VK_FORMAT_R16G16B16_SFLOAT, @@ -332,15 +328,15 @@ pname:indexCount. pname:indexData must: be ename:VK_NULL_HANDLE if pname:indexType is ename:VK_INDEX_TYPE_NONE_NV * [[VUID-VkGeometryTrianglesNV-indexData-02435]] - pname:indexData must: be a valid handle if pname:indexType is not - ename:VK_INDEX_TYPE_NONE_NV + pname:indexData must: be a valid sname:VkBuffer handle if + pname:indexType is not ename:VK_INDEX_TYPE_NONE_NV * [[VUID-VkGeometryTrianglesNV-indexCount-02436]] - pname:indexCount must: be 0 if pname:indexType is + pname:indexCount must: be `0` if pname:indexType is ename:VK_INDEX_TYPE_NONE_NV * [[VUID-VkGeometryTrianglesNV-transformOffset-02437]] pname:transformOffset must: be less than the size of pname:transformData * [[VUID-VkGeometryTrianglesNV-transformOffset-02438]] - pname:transformOffset must: be a multiple of 16 + pname:transformOffset must: be a multiple of `16` **** include::../../validity/structs/VkGeometryTrianglesNV.txt[] @@ -355,24 +351,24 @@ include::../../api/structs/VkGeometryAABBNV.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. - * pname:aabbData is the buffer containing axis-aligned bounding box data + * pname:aabbData is the buffer containing axis-aligned bounding box data. * pname:numAABBs is the number of AABBs in this geometry. * pname:stride is the stride in bytes between AABBs in pname:aabbData. * pname:offset is the offset in bytes of the first AABB in pname:aabbData. +The AABB data in memory is six 32-bit floats consisting of the minimum x, y, +and z values followed by the maximum x, y, and z values. + .Valid Usage **** * [[VUID-VkGeometryAABBNV-offset-02439]] pname:offset must: be less than the size of pname:aabbData * [[VUID-VkGeometryAABBNV-offset-02440]] - pname:offset must: be a multiple of 8. + pname:offset must: be a multiple of `8` * [[VUID-VkGeometryAABBNV-stride-02441]] - pname:stride must: be a multiple of 8. + pname:stride must: be a multiple of `8` **** -The AABB data in memory is 6 32-bit floats consisting of the minimum x, y, -and z values followed by the maximum x, y, and z values. - include::../../validity/structs/VkGeometryAABBNV.txt[] -- @@ -478,40 +474,11 @@ include::../../api/protos/vkBindAccelerationStructureMemoryNV.txt[] * pname:device is the logical device that owns the acceleration structures and memory. - * pname:bindInfoCount is the number of elements in pBindInfos. + * pname:bindInfoCount is the number of elements in pname:pBindInfos. * pname:pBindInfos is a pointer to an array of structures of type slink:VkBindAccelerationStructureMemoryInfoNV, describing images and memory to bind. -.Valid Usage -**** - * [[VUID-vkBindAccelerationStructureMemoryNV-accelerationStructure-02445]] - pname:accelerationStructure must: not already be backed by a memory - object - * [[VUID-vkBindAccelerationStructureMemoryNV-memoryOffset-02446]] - pname:memoryOffset must: be less than the size of pname:memory - * [[VUID-vkBindAccelerationStructureMemoryNV-memory-02447]] - pname:memory must: have been allocated using one of the memory types - allowed in the pname:memoryTypeBits member of the - sname:VkMemoryRequirements structure returned from a call to - fname:vkGetAccelerationStructureMemoryRequirementsNV with - pname:accelerationStructure and pname:type of - ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV - * [[VUID-vkBindAccelerationStructureMemoryNV-memoryOffset-02448]] - pname:memoryOffset must: be an integer multiple of the pname:alignment - member of the sname:VkMemoryRequirements structure returned from a call - to fname:vkGetAccelerationStructureMemoryRequirementsNV with - pname:accelerationStructure and pname:type of - ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV - * [[VUID-vkBindAccelerationStructureMemoryNV-size-02449]] - The pname:size member of the sname:VkMemoryRequirements structure - returned from a call to fname:vkGetImageMemoryRequirements with - pname:accelerationStructure and pname:type of - ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV must: - be less than or equal to the size of pname:memory minus - pname:memoryOffset -**** - include::../../validity/protos/vkBindAccelerationStructureMemoryNV.txt[] -- @@ -525,13 +492,14 @@ include::../../api/structs/VkBindAccelerationStructureMemoryInfoNV.txt[] * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:accelerationStructure is the acceleration structure to be attached to memory. - * pname:memory is a VkDeviceMemory object describing the device memory to - attach. - * pname:memoryOffset is the start offset of the region of memory which is + * pname:memory is a sname:VkDeviceMemory object describing the device + memory to attach. + * pname:memoryOffset is the start offset of the region of memory that is to be bound to the acceleration structure. - The number of bytes returned in the slink:VkMemoryRequirements::size - member in memory, starting from pname:memoryOffset bytes, will be bound - to the specified acceleration structure. + The number of bytes returned in the + slink:VkMemoryRequirements::pname:size member in pname:memory, starting + from pname:memoryOffset bytes, will be bound to the specified + acceleration structure. * pname:deviceIndexCount is the number of elements in pname:pDeviceIndices. * pname:pDeviceIndices is a pointer to an array of device indices. @@ -543,23 +511,24 @@ include::../../api/structs/VkBindAccelerationStructureMemoryInfoNV.txt[] object * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memoryOffset-02451]] pname:memoryOffset must: be less than the size of pname:memory - * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memory-02452]] - pname:memory must: have been allocated using one of the memory types + * pname:memory must: have been allocated using one of the memory types allowed in the pname:memoryTypeBits member of the - sname:VkMemoryRequirements structure returned from a call to - fname:vkGetAccelerationStructureMemoryRequirementsNV with - pname:accelerationStructure - * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memoryOffset-02453]] - pname:memoryOffset must: be an integer multiple of the pname:alignment - member of the sname:VkMemoryRequirements structure returned from a call - to fname:vkGetAccelerationStructureMemoryRequirementsNV with - pname:accelerationStructure - * [[VUID-VkBindAccelerationStructureMemoryInfoNV-size-02454]] - The pname:size member of the sname:VkMemoryRequirements structure + slink:VkMemoryRequirements structure returned from a call to + flink:vkGetAccelerationStructureMemoryRequirementsNV with + pname:accelerationStructure and pname:type of + ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV + * pname:memoryOffset must: be an integer multiple of the pname:alignment + member of the slink:VkMemoryRequirements structure returned from a call + to flink:vkGetAccelerationStructureMemoryRequirementsNV with + pname:accelerationStructure and pname:type of + ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV + * The pname:size member of the sname:VkMemoryRequirements structure returned from a call to - fname:vkGetAccelerationStructureMemoryRequirementsNV with - pname:accelerationStructure must: be less than or equal to the size of - pname:memory minus pname:memoryOffset + flink:vkGetAccelerationStructureMemoryRequirementsNV with + pname:accelerationStructure and pname:type of + ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV must: + be less than or equal to the size of pname:memory minus + pname:memoryOffset **** include::../../validity/structs/VkBindAccelerationStructureMemoryInfoNV.txt[] @@ -581,7 +550,7 @@ include::../../api/protos/vkGetAccelerationStructureHandleNV.txt[] * pname:dataSize is the size in bytes of the buffer pointed to by pname:pData. * pname:pData is a pointer to a user-allocated buffer where the results - will be written + will be written. .Valid Usage **** diff --git a/chapters/VK_NV_ray_tracing/raytracing-shaders.txt b/chapters/VK_NV_ray_tracing/raytracing-shaders.txt index f0b9d590..cdc43b93 100644 --- a/chapters/VK_NV_ray_tracing/raytracing-shaders.txt +++ b/chapters/VK_NV_ray_tracing/raytracing-shaders.txt @@ -37,9 +37,9 @@ ray-primitive intersections and report them. To report an intersection, the shader calls the code:OpReportIntersectionNV instruction. -An intersection shader communicates with any hit and closest shaders by -generating attribute values that they can read. -Intersection shaders cannot read or modify the ray payload. +An intersection shader communicates with any-hit and closest shaders by +generating attribute values that they can: read. +Intersection shaders cannot: read or modify the ray payload. [[shaders-intersection-execution]] === Intersection Shader Execution @@ -51,12 +51,12 @@ guaranteed to be executed at some point during traversal, unless the ray is forcibly terminated. [[shaders-any-hit]] -== Any Hit Shaders +== Any-Hit Shaders -The any hit shader is executed after the intersection shader reports an -intersection that lies within the current [tmin,tmax] of the ray. +The any-hit shader is executed after the intersection shader reports an +intersection that lies within the current [eq]#[tmin,tmax]# of the ray. The main use of any hit shaders is to programmatically decide whether or not -an intersection should be accepted. +an intersection will be accepted. The intersection will be accepted unless the shader calls the code:OpIgnoreIntersectionNV instruction. @@ -64,18 +64,18 @@ code:OpIgnoreIntersectionNV instruction. === Any Hit Shader Execution The order in which intersections are found along a ray, and therefore the -order in which any hit shaders are executed, is unspecified. +order in which any-hit shaders are executed, is unspecified. -The any hit shader of the closest hit is guaranteed to be executed at some +The any-hit shader of the closest hit is guaranteed to be executed at some point during traversal, unless the ray is forcibly terminated. [[shaders-closest-hit]] == Closest Hit Shaders Closest hit shaders have read-only access to the attributes generated by the -corresponding intersection shader, and may: read or modify the ray payload. +corresponding intersection shader, and can: read or modify the ray payload. They also have access to a number of system-generated values. -Closest hit shaders may call code:OpTraceNV to recursively trace rays. +Closest hit shaders can: call code:OpTraceNV to recursively trace rays. [[shaders-closest-hit-execution]] === Closest Hit Shader Execution @@ -86,8 +86,8 @@ intersection has been found and accepted. [[shaders-miss]] == Miss Shaders -Miss shaders can access the ray payload and can trace new rays through the -code:OpTraceNV instruction, but cannot access attributes since they are not +Miss shaders can: access the ray payload and can: trace new rays through the +code:OpTraceNV instruction, but cannot: access attributes since they are not associated with an intersection. [[shaders-miss-execution]] @@ -99,7 +99,7 @@ was found during traversal. [[shaders-callable]] == Callable Shaders -Callable shaders may: access a callable payload that works similarly to ray +Callable shaders can: access a callable payload that works similarly to ray payloads to do subroutine work. [[shaders-callable-execution]] diff --git a/chapters/VK_NV_ray_tracing/raytracing.txt b/chapters/VK_NV_ray_tracing/raytracing.txt index 5f1563dd..f6d1cc13 100644 --- a/chapters/VK_NV_ray_tracing/raytracing.txt +++ b/chapters/VK_NV_ray_tracing/raytracing.txt @@ -1,8 +1,8 @@ [[raytracing]] = Ray Tracing -Unlike draw commands which use rasterization, ray tracing is a rendering -method which generates an image by tracing the path of rays which have a +Unlike draw commands, which use rasterization, ray tracing is a rendering +method that generates an image by tracing the path of rays which have a single origin and using shaders to determine the final colour of an image plane. @@ -21,19 +21,19 @@ Interaction between the different shader stages in the ray tracing pipeline [[raytracing-commands]] == Ray Tracing Commands -_Ray tracing commands_ provoke work in the raytacing pipeline. +_Ray tracing commands_ provoke work in the ray tracing pipeline. Ray tracing commands are recorded into a command buffer and when executed by -a queue will produce work which executes according to the currently bound +a queue will produce work that executes according to the currently bound ray tracing pipeline. A ray tracing pipeline must: be bound to a command buffer before any ray tracing commands are recorded in that command buffer. Each ray tracing call operates on a set of shader stages that are specific to the ray tracing pipeline as well as a set of -sname:VkAccelerationStructureNV objects which describe the scene geometry in -an implementation-specific way. +sname:VkAccelerationStructureNV objects, which describe the scene geometry +in an implementation-specific way. The relationship between the ray tracing pipeline object and the -acceleration structures is passed into the raytacing command in a +acceleration structures is passed into the ray tracing command in a slink:VkBuffer object known as a _shader binding table_. During execution, control alternates between scheduling and other @@ -48,7 +48,7 @@ function. The programmable portions of the pipeline are exposed in a single-ray programming model. Each GPU thread handles one ray at a time. -Memory operations can be synchronized using standard memory barriers. +Memory operations can: be synchronized using standard memory barriers. However, communication and synchronization between threads is not allowed. In particular, the use of compute pipeline synchronization functions is not supported in the ray tracing pipeline. @@ -73,21 +73,21 @@ include::../../api/protos/vkCmdTraceRaysNV.txt[] pname:missShaderBindingTableBuffer) of the miss shader being used for the trace. * pname:missShaderBindingStride is the size in bytes of each shader - binding table record in pname:missShaderBindingTableBuffer + binding table record in pname:missShaderBindingTableBuffer. * pname:hitShaderBindingTableBuffer is the buffer object that holds the shader binding table data for the hit shader stages. * pname:hitShaderBindingOffset is the offset in bytes (relative to pname:hitShaderBindingTableBuffer) of the hit shader group being used for the trace. * pname:hitShaderBindingStride is the size in bytes of each shader binding - table record in pname:hitShaderBindingTableBuffer + table record in pname:hitShaderBindingTableBuffer. * pname:callableShaderBindingTableBuffer is the buffer object that holds the shader binding table data for the callable shader stage. * pname:callableShaderBindingOffset is the offset in bytes (relative to pname:callableShaderBindingTableBuffer) of the callable shader being used for the trace. * pname:callableShaderBindingStride is the size in bytes of each shader - binding table record in pname:callableShaderBindingTableBuffer + binding table record in pname:callableShaderBindingTableBuffer. * pname:width is the width of the ray trace query dimensions. * pname:height is height of the ray trace query dimensions. * pname:depth is depth of the ray trace query dimensions. @@ -102,25 +102,25 @@ When the command is executed, a ray generation group of [eq]#pname:width pname:raygenShaderBindingTableBuffer * [[VUID-vkCmdTraceRaysNV-raygenShaderBindingOffset-02456]] pname:raygenShaderBindingOffset must: be a multiple of - sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment. + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment * [[VUID-vkCmdTraceRaysNV-missShaderBindingOffset-02457]] pname:missShaderBindingOffset must: be less than the size of pname:missShaderBindingTableBuffer * [[VUID-vkCmdTraceRaysNV-missShaderBindingOffset-02458]] pname:missShaderBindingOffset must: be a multiple of - sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment. + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment * [[VUID-vkCmdTraceRaysNV-hitShaderBindingOffset-02459]] pname:hitShaderBindingOffset must: be less than the size of pname:hitShaderBindingTableBuffer * [[VUID-vkCmdTraceRaysNV-hitShaderBindingOffset-02460]] pname:hitShaderBindingOffset must: be a multiple of - sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment. + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment * [[VUID-vkCmdTraceRaysNV-callableShaderBindingOffset-02461]] pname:callableShaderBindingOffset must: be less than the size of pname:callableShaderBindingTableBuffer * [[VUID-vkCmdTraceRaysNV-callableShaderBindingOffset-02462]] pname:callableShaderBindingOffset must: be a multiple of - sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment. + sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupBaseAlignment * [[VUID-vkCmdTraceRaysNV-missShaderBindingStride-02463]] pname:missShaderBindingStride must: be a multiple of sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupHandleSize @@ -208,13 +208,13 @@ When the command is executed, a ray generation group of [eq]#pname:width If a sname:VkImageView is sampled with ename:VK_FILTER_LINEAR as a result of this command, then the image view's <> must: contain - ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT. + ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT ifdef::VK_IMG_filter_cubic[] * [[VUID-vkCmdTraceRaysNV-None-02482]] If a sname:VkImageView is sampled with ename:VK_FILTER_CUBIC_IMG as a result of this command, then the image view's <> must: contain - ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG. + ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG * [[VUID-vkCmdTraceRaysNV-None-02483]] Any slink:VkImageView being sampled with ename:VK_FILTER_CUBIC_IMG as a result of this command must: not have a elink:VkImageViewType of @@ -227,19 +227,19 @@ ifdef::VK_VERSION_1_1[] pipeline stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV reads from or writes to any image or buffer, that image or buffer must: not be a protected image or - protected buffer. + protected buffer * [[VUID-vkCmdTraceRaysNV-commandBuffer-02485]] If pname:commandBuffer is a protected command buffer, and any pipeline stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV writes to any image or buffer, that image or buffer must: not be an unprotected image or - unprotected buffer. + unprotected buffer * [[VUID-vkCmdTraceRaysNV-commandBuffer-02486]] If pname:commandBuffer is a protected command buffer, and any pipeline stage other than the ray tracing pipeline stage in the sname:VkPipeline object bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_NV reads from any image or buffer, the image or buffer must: not be a protected image - or protected buffer. + or protected buffer endif::VK_VERSION_1_1[] ifdef::VK_NV_corner_sampled_image[] * [[VUID-vkCmdTraceRaysNV-flags-02487]] @@ -247,7 +247,7 @@ ifdef::VK_NV_corner_sampled_image[] containing ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must: only be sampled using a elink:VkSamplerAddressMode of - ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. + ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE endif::VK_NV_corner_sampled_image[] **** @@ -273,10 +273,10 @@ pname:shaderGroupHandleSize bytes of data as queried by flink:vkGetRayTracingShaderGroupHandlesNV to refer to the shader that it invokes. The remainder of the data specified by the stride is application-visible -data that can be referenced by a shaderRecordNV block in the shader. +data that can be referenced by a code:shaderRecordNV block in the shader. The shader binding tables to use in a ray tracing query are passed to -fname:vkCmdTraceRaysNV. +flink:vkCmdTraceRaysNV. Shader binding tables are read-only in shaders that are executing on the ray tracing pipeline. @@ -285,7 +285,7 @@ tracing pipeline. === Indexing Rules In order to execute the correct shaders and access the correct resources -during a ray tracing dispatch, the implementation must be able to locate +during a ray tracing dispatch, the implementation must: be able to locate shader binding table entries at various stages of execution. This is accomplished by defining a set of indexing rules that compute shader binding table record positions relative to the buffer's base address in @@ -298,15 +298,15 @@ records. ==== Ray Generation Shaders Only one ray generation shader is executed per ray tracing dispatch. -Its location is passed into fname:vkCmdTraceRaysNV using the +Its location is passed into flink:vkCmdTraceRaysNV using the pname:raygenShaderBindingTableBuffer and -pname:raygenShaderBindingTableOffset parameters - there is no indexing. +pname:raygenShaderBindingTableOffset parameters -- there is no indexing. ==== Hit Shaders -The base for the computation of intersection, any hit and closest hit shader -locations is the pname:instanceShaderBindingTableRecordOffset value stored +The base for the computation of intersection, any-hit and closest hit shader +locations is the code:instanceShaderBindingTableRecordOffset value stored with each instance of a top-level acceleration structure. This value determines the beginning of the shader binding table records for a given instance. @@ -315,40 +315,41 @@ Each geometry in the instance must: have at least one hit program record. In the following rule, _geometryIndex_ refers to the location of the geometry within the instance. -The pname:sbtRecordStride and pname:sbtRecordOffset values are passed in as +The code:sbtRecordStride and code:sbtRecordOffset values are passed in as parameters to code:traceNV() calls made in the shaders. See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language Specification for more details. The result of this computation is then added to pname:hitProgramShaderBindingTableBaseIndex, a base index passed to -fname:vkCmdTraceRaysNV. +flink:vkCmdTraceRaysNV. The complete rule to compute a hit shader binding table record index is: - :: [eq]#instanceShaderBindingTableRecordOffset {plus} - hitProgramShaderBindingTableBaseIndex {plus} geometryIndex {times} - sbtRecordStride {plus} sbtRecordOffset# + :: [eq]#code:instanceShaderBindingTableRecordOffset {plus} + code:hitProgramShaderBindingTableBaseIndex {plus} _geometryIndex_ + {times} code:sbtRecordStride {plus} code:sbtRecordOffset# ==== Miss Shaders A Miss shader is executed whenever a ray query fails to find an intersection for the given scene geometry. -Multiple miss shaders can be executed throughout a ray tracing dispatch. +Multiple miss shaders may: be executed throughout a ray tracing dispatch. The base for the computation of miss shader locations is -pname:missProgramShaderBindingTableBaseIndex, a base index passed into -fname:vkCmdTraceRaysNV. +code:missProgramShaderBindingTableBaseIndex, a base index passed into +flink:vkCmdTraceRaysNV. -The pname:sbtRecordOffset value is passed in as parameters to code:traceNV() +The code:sbtRecordOffset value is passed in as parameters to code:traceNV() calls made in the shaders. See Section 8.19 (Ray Tracing Functions) of the OpenGL Shading Language Specification for more details. The complete rule to compute a miss shader binding table record address is: - :: [eq]#missIndex {times} missShaderBindingStride {plus} sbtRecordOffset# + :: [eq]#code:missProgramShaderBindingTableBaseIndex {times} + pname:missShaderBindingStride {plus} code:sbtRecordOffset# [[acceleration-structure]] @@ -360,7 +361,7 @@ tracing query. The application is responsible for managing acceleration structure objects (see <>, including allocation, destruction, executing builds or updates, and -synchronizing resources used uring ray tracing queries. +synchronizing resources used during ray tracing queries. There are two types of acceleration structures, _top level acceleration structures_ and _bottom level acceleration structures_. @@ -381,7 +382,7 @@ structures. _Instances_ are found in top level acceleration structures and contain data that refer to a single bottom-level acceleration structure, a transform matrix, and shading information. -Multiple instances may point to a single bottom level acceleration +Multiple instances can: point to a single bottom level acceleration structure. An instance is defined in a slink:VkBuffer by a structure consisting of 64 @@ -392,22 +393,23 @@ bytes of data. * pname:instanceCustomIndex The low 24 bits of a 32-bit integer after the transform. This value appears in the builtin code:gl_InstanceCustomIndexNV - * pname:mask The high 8 bits of the same integer as instanceCustomIndex. + * pname:mask The high 8 bits of the same integer as + pname:instanceCustomIndex. This is the visibility mask. - The instance can only be hit if rayMask & instance.mask != 0 + The instance may: only be hit if `rayMask & instance.mask != 0` * pname:instanceOffset The low 24 bits of the next 32-bit integer. The value contributed by this instance to the hit shader binding table - index computation as instanceShaderBindingTableRecordOffset. - * pname:flags The high 8 bits of the same integer as instanceOffset. - VkGeometryInstanceFlagBitsNV values that apply to this instance. + index computation as code:instanceShaderBindingTableRecordOffset. + * pname:flags The high 8 bits of the same integer as pname:instanceOffset. + slink:VkGeometryInstanceFlagBitsNV values that apply to this instance. * pname:accelerationStructure. - The 8 byte value returned by vkGetAccelerationStructureHandleNV for the - bottom level acceleration structure referred to by this instance. + The 8 byte value returned by flink:vkGetAccelerationStructureHandleNV + for the bottom level acceleration structure referred to by this instance. [NOTE] .Note ==== -The C language spec doesn't define the ordering of bit-fields, but in +The C language spec does not define the ordering of bit-fields, but in practice, this struct produces the layout described above: [source,c] @@ -436,19 +438,19 @@ include::../../api/enums/VkGeometryInstanceFlagBitsNV.txt[] culling for this instance. * ename:VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_NV indicates that the front face of the triangle for culling purposes - should be the face that's counter clockwise in object space relative to - the ray origin. + is the face that is counter clockwise in object space relative to the + ray origin. Because the facing is determined in object space, an instance transform - matrix does not changing winding, but a geometry transform does. + matrix does not change the winding, but a geometry transform does. * ename:VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_NV causes this instance to act as though ename:VK_GEOMETRY_OPAQUE_BIT_NV were specified on all geometries referenced by this instance. - This behavior can be overridden by the ray flag + This behavior can: be overridden by the ray flag code:gl_RayFlagsNoOpaqueNV. * ename:VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_NV causes this instance to act as though ename:VK_GEOMETRY_OPAQUE_BIT_NV were not specified on all geometries referenced by this instance. - This behavior can be overridden by the ray flag + This behavior can: be overridden by the ray flag code:gl_RayFlagsOpaqueNV. ename:VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_NV and @@ -496,63 +498,64 @@ To build an acceleration structure call: include::../../api/protos/vkCmdBuildAccelerationStructureNV.txt[] * pname:commandBuffer is the command buffer into which the command will be - recorded - * pname:info contains the shared information for the acceleration - structure's structure + recorded. + * pname:pInfo contains the shared information for the acceleration + structure's structure. * pname:instanceData is the buffer containing instance data that will be used to build the acceleration structure as described in <> - This parameter must: be NULL for bottom level acceleration structures. + This parameter must: be `NULL` for bottom level acceleration structures. * pname:instanceOffset is the offset in bytes (relative to the start of pname:instanceData) at which the instance data is located. * pname:update specifies whether to update the pname:dst acceleration structure with the data in pname:src. * pname:dst points to the target acceleration structure for the build. - * pname:src points to an existing acceleration structure that can be used - to update the pname:dst acceleration structure. + * pname:src points to an existing acceleration structure that is to be + used to update the pname:dst acceleration structure. * pname:scratch is the slink:VkBuffer that will be used as scratch memory for the build. * pname:scratchOffset is the offset in bytes relative to the start of - pname:scratch that will be used as scratch memory. + pname:scratch that will be used as a scratch memory. .Valid Usage **** * [[VUID-vkCmdBuildAccelerationStructureNV-geometryCount-02241]] pname:geometryCount must: be less than or equal to - sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount + slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount * [[VUID-vkCmdBuildAccelerationStructureNV-dst-02488]] pname:dst must: have been created with compatible - sname:VkAccelerationStructureInfoNV where - sname:VkAccelerationStructureInfoNV:::pname:type and - sname:VkAccelerationStructureInfoNV::pname:flags are identical, - sname:VkAccelerationStructureInfoNV::pname:instanceCount and - sname:VkAccelerationStructureInfoNV::pname:geometryCount for pname:dst + slink:VkAccelerationStructureInfoNV where + slink:VkAccelerationStructureInfoNV:::pname:type and + slink:VkAccelerationStructureInfoNV::pname:flags are identical, + slink:VkAccelerationStructureInfoNV::pname:instanceCount and + slink:VkAccelerationStructureInfoNV::pname:geometryCount for pname:dst are greater than or equal to the build size and each geometry in - sname:VkAccelerationStructureInfoNV::pname:pGeometries for pname:dst has + slink:VkAccelerationStructureInfoNV::pname:pGeometries for pname:dst has greater than or equal to the number of vertices, indices, and AABBs. * [[VUID-vkCmdBuildAccelerationStructureNV-update-02489]] - If pname:update is true, pname:src must: not be ename:VK_NULL_HANDLE + If pname:update is ename:VK_TRUE, pname:src must: not be + ename:VK_NULL_HANDLE * [[VUID-vkCmdBuildAccelerationStructureNV-update-02490]] - If pname:update is true, pname:src must: have been built last with + If pname:update is ename:VK_TRUE, pname:src must: have been built before with ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV set in - sname:VkAccelerationStructureInfoNV::pname:flags + slink:VkAccelerationStructureInfoNV::pname:flags * [[VUID-vkCmdBuildAccelerationStructureNV-update-02491]] - If pname:update is false, The pname:size member of the - sname:VkMemoryRequirements structure returned from a call to - fname:vkGetAccelerationStructureMemoryRequirementsNV with - sname:VkAccelerationStructureMemoryRequirementsInfoNV::pname:accelerationStructure + If pname:update is ename:VK_FALSE, The pname:size member of the + slink:VkMemoryRequirements structure returned from a call to + flink:vkGetAccelerationStructureMemoryRequirementsNV with + slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:accelerationStructure set to pname:dst and - sname:VkAccelerationStructureMemoryRequirementsInfoNV::pname:type set to + slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:type set to ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV must: be less than or equal to the size of pname:scratch minus pname:scratchOffset * [[VUID-vkCmdBuildAccelerationStructureNV-update-02492]] - If pname:update is true, The pname:size member of the - sname:VkMemoryRequirements structure returned from a call to - fname:vkGetAccelerationStructureMemoryRequirementsNV with - sname:VkAccelerationStructureMemoryRequirementsInfoNV::pname:accelerationStructure + If pname:update is ename:VK_TRUE, The pname:size member of the + slink:VkMemoryRequirements structure returned from a call to + flink:vkGetAccelerationStructureMemoryRequirementsNV with + slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:accelerationStructure set to pname:dst and - sname:VkAccelerationStructureMemoryRequirementsInfoNV::pname:type set to + slink:VkAccelerationStructureMemoryRequirementsInfoNV::pname:type set to ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV must: be less than or equal to the size of pname:scratch minus pname:scratchOffset @@ -567,7 +570,7 @@ include::../../validity/protos/vkCmdBuildAccelerationStructureNV.txt[] An additional command exists for copying acceleration structures without updating their contents. -The acceleration structure object may: be compacted in order to improve +The acceleration structure object can: be compacted in order to improve performance. Before copying, an application must: query the size of the resulting acceleration structure. @@ -584,14 +587,14 @@ include::../../api/protos/vkCmdWriteAccelerationStructuresPropertiesNV.txt[] recorded. * pname:accelerationStructureCount is the count of acceleration structures for which to query the property. - * pname:accelerationStructures points to an array of existing acceleration - structures which have been built. + * pname:pAccelerationStructures points to an array of existing previously + built acceleration structures. * pname:queryType is a elink:VkQueryType value specifying the type of queries managed by the pool. * pname:queryPool is the query pool that will manage the results of the query. * pname:firstQuery is the first query index within the query pool that - will contain the pname:accelerationStructureCount number of results + will contain the pname:accelerationStructureCount number of results. .Valid Usage **** @@ -626,8 +629,8 @@ include::../../api/protos/vkCmdCopyAccelerationStructureNV.txt[] * pname:commandBuffer is the command buffer into which the command will be recorded. - * pname:dst points to the target acceleration structure for the copy - * pname:src points to the source acceleration structure for the copy + * pname:dst points to the target acceleration structure for the copy. + * pname:src points to the source acceleration structure for the copy. * pname:mode is a elink:VkCopyAccelerationStructureModeNV value that specifies additional operations to perform during the copy. diff --git a/chapters/drawing.txt b/chapters/drawing.txt index bd984674..afccc57d 100644 --- a/chapters/drawing.txt +++ b/chapters/drawing.txt @@ -487,7 +487,7 @@ include::../api/protos/vkCmdBindIndexBuffer.txt[] contiguously to a single sname:VkDeviceMemory object ifdef::VK_NV_ray_tracing[] * [[VUID-vkCmdBindIndexBuffer-indexType-02507]] - pname:indexType must: not be VK_INDEX_TYPE_NONE_NV. + pname:indexType must: not be ename:VK_INDEX_TYPE_NONE_NV. endif::VK_NV_ray_tracing[] **** @@ -508,7 +508,7 @@ include::../api/enums/VkIndexType.txt[] * ename:VK_INDEX_TYPE_UINT32 specifies that indices are 32-bit unsigned integer values. ifdef::VK_NV_ray_tracing[] - * ename:VK_INDEX_TYPE_NONE_NV specifies no indices are provided. + * ename:VK_INDEX_TYPE_NONE_NV specifies that no indices are provided. endif::VK_NV_ray_tracing[] --