vulkan-3.27: src/Vulkan/Extensions/VK_HUAWEI_cluster_culling_shader.hs-boot
{-# language CPP #-}
-- | = Name
--
-- VK_HUAWEI_cluster_culling_shader - device extension
--
-- = VK_HUAWEI_cluster_culling_shader
--
-- [__Name String__]
-- @VK_HUAWEI_cluster_culling_shader@
--
-- [__Extension Type__]
-- Device extension
--
-- [__Registered Extension Number__]
-- 405
--
-- [__Revision__]
-- 3
--
-- [__Ratification Status__]
-- Not ratified
--
-- [__Extension and Version Dependencies__]
-- <https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_get_physical_device_properties2 VK_KHR_get_physical_device_properties2>
-- or
-- <https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#versions-1.1 Vulkan Version 1.1>
--
-- [__SPIR-V Dependencies__]
--
-- - <https://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/HUAWEI/SPV_HUAWEI_cluster_culling_shader.html SPV_HUAWEI_cluster_culling_shader>
--
-- [__Contact__]
--
-- - Yuchang Wang
-- <https://github.com/KhronosGroup/Vulkan-Docs/issues/new?body=[VK_HUAWEI_cluster_culling_shader] @richard_Wang2%0A*Here describe the issue or question you have about the VK_HUAWEI_cluster_culling_shader extension* >
--
-- [__Extension Proposal__]
-- <https://github.com/KhronosGroup/Vulkan-Docs/tree/main/proposals/VK_HUAWEI_cluster_culling_shader.adoc VK_HUAWEI_cluster_culling_shader>
--
-- == Other Extension Metadata
--
-- [__Last Modified Date__]
-- 2023-08-16
--
-- [__Interactions and External Dependencies__]
--
-- - This extension provides API support for
-- <https://github.com/KhronosGroup/GLSL/blob/main/extensions/huawei/GLSL_HUAWEI_cluster_culling_shader.txt GL_HUAWEI_cluster_culling_shader>.
--
-- [__Contributors__]
--
-- - Yuchang Wang, Huawei
--
-- - Juntao Li, Huawei
--
-- - Pan Gao, Huawei
--
-- - Jie Cao, Huawei
--
-- - Yunjin Zhang, Huawei
--
-- - Shujie Zhou, Huawei
--
-- - Chaojun Wang, Huawei
--
-- - Jiajun Hu, Huawei
--
-- - Cong Zhang, Huawei
--
-- == Description
--
-- Cluster Culling Shaders (CCS) are similar to the existing compute
-- shaders. Their main purpose is to provide an execution environment in
-- order to perform coarse-level geometry culling and LOD selection more
-- efficiently on the GPU.
--
-- The traditional 2-pass GPU culling solution using a compute shader
-- sometimes needs a pipeline barrier between compute and graphics pipeline
-- to optimize performance. An additional compaction process may also be
-- required. This extension addresses these shortcomings, allowing compute
-- shaders to directly emit visible clusters to the following graphics
-- pipeline.
--
-- A set of new built-in output variables are used to express a visible
-- cluster, including per-cluster shading rate. In addition, a new built-in
-- function is used to emit these variables from CCS to the IA stage. The
-- IA stage can use these variables to fetch vertices of a visible cluster
-- and drive vertex shaders to shading these vertices.
--
-- Note that CCS do not work with geometry or tessellation shaders, but
-- both IA and vertex shaders are preserved. Vertex shaders are still used
-- for vertex position shading, instead of directly outputting transformed
-- vertices from the compute shader. This makes CCS more suitable for
-- mobile GPUs.
--
-- == New Commands
--
-- - 'cmdDrawClusterHUAWEI'
--
-- - 'cmdDrawClusterIndirectHUAWEI'
--
-- == New Structures
--
-- - Extending 'PhysicalDeviceClusterCullingShaderFeaturesHUAWEI':
--
-- - 'PhysicalDeviceClusterCullingShaderVrsFeaturesHUAWEI'
--
-- - Extending
-- 'Vulkan.Core11.Promoted_From_VK_KHR_get_physical_device_properties2.PhysicalDeviceFeatures2',
-- 'Vulkan.Core10.Device.DeviceCreateInfo':
--
-- - 'PhysicalDeviceClusterCullingShaderFeaturesHUAWEI'
--
-- - Extending
-- 'Vulkan.Core11.Promoted_From_VK_KHR_get_physical_device_properties2.PhysicalDeviceProperties2':
--
-- - 'PhysicalDeviceClusterCullingShaderPropertiesHUAWEI'
--
-- == New Enum Constants
--
-- - 'HUAWEI_CLUSTER_CULLING_SHADER_EXTENSION_NAME'
--
-- - 'HUAWEI_CLUSTER_CULLING_SHADER_SPEC_VERSION'
--
-- - Extending
-- 'Vulkan.Core13.Enums.PipelineStageFlags2.PipelineStageFlagBits2':
--
-- - 'Vulkan.Core13.Enums.PipelineStageFlags2.PIPELINE_STAGE_2_CLUSTER_CULLING_SHADER_BIT_HUAWEI'
--
-- - Extending
-- 'Vulkan.Core10.Enums.QueryPipelineStatisticFlagBits.QueryPipelineStatisticFlagBits':
--
-- - 'Vulkan.Core10.Enums.QueryPipelineStatisticFlagBits.QUERY_PIPELINE_STATISTIC_CLUSTER_CULLING_SHADER_INVOCATIONS_BIT_HUAWEI'
--
-- - Extending
-- 'Vulkan.Core10.Enums.ShaderStageFlagBits.ShaderStageFlagBits':
--
-- - 'Vulkan.Core10.Enums.ShaderStageFlagBits.SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI'
--
-- - Extending 'Vulkan.Core10.Enums.StructureType.StructureType':
--
-- - 'Vulkan.Core10.Enums.StructureType.STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_CULLING_SHADER_FEATURES_HUAWEI'
--
-- - 'Vulkan.Core10.Enums.StructureType.STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_CULLING_SHADER_PROPERTIES_HUAWEI'
--
-- - 'Vulkan.Core10.Enums.StructureType.STRUCTURE_TYPE_PHYSICAL_DEVICE_CLUSTER_CULLING_SHADER_VRS_FEATURES_HUAWEI'
--
-- == New Built-In Variables
--
-- - <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-builtin-variables-indexcounthuawei IndexCountHUAWEI>
--
-- - <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-builtin-variables-vertexcounthuawei VertexCountHUAWEI>
--
-- - <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-builtin-variables-instancecounthuawei InstanceCountHUAWEI>
--
-- - <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-builtin-variables-firstindexhuawei FirstIndexHUAWEI>
--
-- - <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-builtin-variables-firstvertexhuawei FirstVertexHUAWEI>
--
-- - <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-builtin-variables-vertexoffsethuawei VertexOffsetHUAWEI>
--
-- - <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-builtin-variables-firstinstancehuawei FirstInstanceHUAWEI>
--
-- - <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-builtin-variables-clusteridhuawei ClusterIDHUAWEI>
--
-- - <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#interfaces-builtin-variables-clustershadingratehuawei ClusterShadingRateHUAWEI>
--
-- == New SPIR-V Capability
--
-- - <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#spirvenv-capabilities-table-ClusterCullingShadingHUAWEI ClusterCullingShadingHUAWEI>
--
-- == Sample Code
--
-- Example of cluster culling in a GLSL shader
--
-- > #extension GL_HUAWEI_cluster_culling_shader: enable
-- >
-- > #define GPU_WARP_SIZE 32
-- > #define GPU_GROUP_SIZE GPU_WARP_SIZE
-- >
-- > #define GPU_CLUSTER_PER_INVOCATION 1
-- > #define GPU_CLUSTER_PER_WORKGROUP (GPU_GROUP_SIZE * GPU_CLUSTER_PER_INVOCATION)
-- >
-- > // Number of threads per workgroup
-- > // - 1D only
-- > // - warpsize = 32
-- > layout(local_size_x=GPU_GROUP_SIZE, local_size_y=1, local_size_z=1) in;
-- >
-- > #define GPU_DRAW_BUFFER_BINDING 0
-- > #define GPU_INSTANCE_DESCRIPTOR_BINDING 1
-- >
-- > struct BoundingSphere
-- > {
-- > vec3 center;
-- > float radius;
-- > };
-- >
-- > struct InstanceData
-- > {
-- > mat4 mvp_matrix; // mvp matrix.
-- > vec4 frustum_planes[6]; // six frustum planes
-- > mat4 model_matrix_transpose_inverse; // inverse transpose of model matrix.
-- > vec3 view_origin; // view original
-- > };
-- >
-- > struct InstanceDescriptor
-- > {
-- > uint begin;
-- > uint end;
-- > uint cluster_count;
-- > uint debug;
-- > BoundingSphere sphere;
-- > InstanceData instance_data;
-- > };
-- >
-- > struct DrawElementsCommand{
-- > uint indexcount;
-- > uint instanceCount;
-- > uint firstIndex;
-- > int vertexoffset;
-- > uint firstInstance;
-- > uint cluster_id;
-- > };
-- >
-- > // indexed mode
-- > out gl_PerClusterHUAWEI{
-- > uint gl_IndexCountHUAWEI;
-- > uint gl_InstanceCountHUAWEI;
-- > uint gl_FirstIndexHUAWEI;
-- > int gl_VertexOffsetHUAWEI;
-- > uint gl_FirstInstanceHUAWEI;
-- > uint gl_ClusterIDHUAWEI;
-- > uint gl_ClusterShadingRateHUAWEI;
-- > };
-- >
-- > layout(binding = GPU_DRAW_BUFFER_BINDING, std430) buffer draw_indirect_ssbo
-- > {
-- > DrawElementsCommand draw_commands[];
-- > };
-- >
-- > layout(binding = GPU_INSTANCE_DESCRIPTOR_BINDING, std430) buffer instance_descriptor_ssbo
-- > {
-- > InstanceDescriptor instance_descriptors[];
-- > };
-- >
-- >
-- > float Distance(uint instance_id)
-- > {
-- > vec3 v = normalize(instance_descriptor[instance_id].sphere.center -
-- > instance_descriptor[instance_id].instance_data.view_origin);
-- > float dist = sqrt(dot(v,v));
-- >
-- > return dist;
-- > }
-- >
-- > bool isSphereOutsideFrustum( vec3 sphere_center, float sphere_radius )
-- > {
-- > bool isInside = false;
-- >
-- > for(int i = 0; i < 6; i++)
-- > {
-- > isInside = isInside ||
-- > (dot(instance_descriptors[instance_id].instance_data.frustum_planes[i].xyz,
-- > sphere_center) + instance_descriptors[instance_id].instance_data.frustum_planes[i].w <
-- > sphere_radius);
-- > }
-- > return isInside;
-- > }
-- >
-- >
-- > void main()
-- > {
-- > // get instance description
-- > instance_id = gl_GlobalInvocationID.x;
-- > InstanceDescriptor inst_desc = instance_descriptors[instance_id];
-- >
-- > //instance based culling
-- > bool render = !isSphereOutsideFrustum(inst_desc.sphere.center, inst_desc.sphere.radius);
-- >
-- > if (render)
-- > {
-- > // calculate distance
-- > float distance = Distance(instance_id);
-- >
-- > // update shading rate built-in variable
-- > if(distance > 0.7)
-- > gl_ClusterShadingRateHUAWEI =
-- > gl_ShadingRateFlag4VerticalPixelsEXT | gl_ShadingRateFlag4HorizontalPixelsEXT;
-- > else if(distance > 0.3)
-- > gl_ClusterShadingRateHUAWEI =
-- > gl_ShadingRateFlag2VerticalPixelsEXT | gl_ShadingRateFlag2HorizontalPixelsEXT;
-- > else
-- > gl_ClusterShadingRateHUAWEI = 0;
-- >
-- > // this is a visible cluster, update built-in output variable.
-- > // in case of indexed mode:
-- > gl_IndexCountHUAWEI = draw_commands[cluster_id].indexcount;
-- > gl_InstanceCountHUAWEI = draw_commands[cluster_id].instanceCount;
-- > gl_FirstIndexHUAWEI = draw_commands[cluster_id].firstIndex;
-- > gl_VertexOffsetHUAWEI = draw_commands[cluster_id].vertexoffset;
-- > gl_FirstInstanceHUAWEI = draw_commands[cluster_id].firstInstance;
-- > gl_ClusterIDHUAWEI = draw_commands[cluster_id].cluster_id;
-- >
-- > // emit built-in output variables as a drawing command to subsequent
-- > // rendering pipeline.
-- > dispatchClusterHUAWEI();
-- > }
-- > }
--
-- Example of graphics pipeline creation with cluster culling shader
--
-- > // create a cluster culling shader stage info structure.
-- > VkPipelineShaderStageCreateInfo ccsStageInfo{};
-- > ccsStageInfo.sType = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO;
-- > ccsStageInfo.stage = VK_SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI;
-- > ccsStageInfo.module = clustercullingshaderModule;
-- > ccsStageInfo.pName = "main";
-- >
-- > // pipeline shader stage creation
-- > VkPipelineShaderStageCreateInfo shaderStages[] = { ccsStageInfo, vertexShaderStageInfo, fragmentShaderStageInfo };
-- >
-- > // create graphics pipeline
-- > VkGraphicsPipelineCreateInfo pipelineInfo{};
-- > pipelineInfo.sType = VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO;
-- > pipelineInfo.stageCount = 3;
-- > pipelineInfo.pStage = shaderStages;
-- > pipelineInfo.pVertexInputState = &vertexInputInfo;
-- > // ...
-- > VkPipeline graphicsPipeline;
-- > VkCreateGraphicsPipelines(device, VK_NULL_HANDLE, 1, &pipelineInfo, nullptr, &graphicsPipeline);
--
-- Example of launching the execution of cluster culling shader
--
-- > vkCmdBindPipeline(commandBuffer, VK_PIPELINE_BIND_POINT_GRAPHICS, graphicsPipeline);
-- > vkCmdDrawClusterHUAWEI(commandBuffer, groupCountX, 1, 1);
-- > vkCmdEndRenderPass(commandBuffer);
--
-- == Version History
--
-- - Revision 1, 2022-11-18 (YuChang Wang)
--
-- - Internal revisions
--
-- - Revision 2, 2023-04-02 (Jon Leech)
--
-- - Grammar edits.
--
-- - Revision 3, 2023-08-21 (YuChang Wang)
--
-- - Add per-cluster shading rate.
--
-- == See Also
--
-- No cross-references are available
--
-- == Document Notes
--
-- For more information, see the
-- <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#VK_HUAWEI_cluster_culling_shader Vulkan Specification>.
--
-- This page is a generated document. Fixes and changes should be made to
-- the generator scripts, not directly.
module Vulkan.Extensions.VK_HUAWEI_cluster_culling_shader ( PhysicalDeviceClusterCullingShaderFeaturesHUAWEI
, PhysicalDeviceClusterCullingShaderPropertiesHUAWEI
, PhysicalDeviceClusterCullingShaderVrsFeaturesHUAWEI
) where
import Vulkan.CStruct (FromCStruct)
import Vulkan.CStruct (ToCStruct)
import Data.Kind (Type)
import {-# SOURCE #-} Vulkan.CStruct.Extends (Chain)
import {-# SOURCE #-} Vulkan.CStruct.Extends (Extendss)
import {-# SOURCE #-} Vulkan.CStruct.Extends (PeekChain)
import {-# SOURCE #-} Vulkan.CStruct.Extends (PokeChain)
type role PhysicalDeviceClusterCullingShaderFeaturesHUAWEI nominal
data PhysicalDeviceClusterCullingShaderFeaturesHUAWEI (es :: [Type])
instance ( Extendss PhysicalDeviceClusterCullingShaderFeaturesHUAWEI es
, PokeChain es ) => ToCStruct (PhysicalDeviceClusterCullingShaderFeaturesHUAWEI es)
instance Show (Chain es) => Show (PhysicalDeviceClusterCullingShaderFeaturesHUAWEI es)
instance ( Extendss PhysicalDeviceClusterCullingShaderFeaturesHUAWEI es
, PeekChain es ) => FromCStruct (PhysicalDeviceClusterCullingShaderFeaturesHUAWEI es)
data PhysicalDeviceClusterCullingShaderPropertiesHUAWEI
instance ToCStruct PhysicalDeviceClusterCullingShaderPropertiesHUAWEI
instance Show PhysicalDeviceClusterCullingShaderPropertiesHUAWEI
instance FromCStruct PhysicalDeviceClusterCullingShaderPropertiesHUAWEI
data PhysicalDeviceClusterCullingShaderVrsFeaturesHUAWEI
instance ToCStruct PhysicalDeviceClusterCullingShaderVrsFeaturesHUAWEI
instance Show PhysicalDeviceClusterCullingShaderVrsFeaturesHUAWEI
instance FromCStruct PhysicalDeviceClusterCullingShaderVrsFeaturesHUAWEI