Kanzi graphics¶

Kanzi graphics (kzgfx) 是 Kanzi 的渲染硬件接口 (RHI)。它提供了一个抽象层，使 Kanzi 能够使用不同的图形 API。Kanzi 提供了该接口的以下实现：

基于 OpenGL 的后端，支持 OpenGL 3.3+、OpenGL ES 3.0+ 和 WebGL 2.0
Vulkan 1.1+ 后端

大多数 Kanzi 应用程序无需直接使用 Kanzi graphics API，而是使用 Rendering 系统中的高级概念。仅在实现计算或手动渲染等高级用例时，才直接使用 Kanzi graphics。

Kanzi graphics API 包含以下主要组件：

图形对象表示接口中的实体，例如缓冲区、图像或着色器。
命令对图形对象进行操作，并被收集到命令缓冲区中以延迟执行。复制、绘制和呈现等操作是典型的命令。

Kanzi graphics 使用的着色器程序除了原始着色器源代码之外，还必须提供反射信息。在大多数用例中，Kanzi Studio 会在导出工程时自动完成此操作，但您也可以使用 Kanzi Shader Compiler library 或通过手动构建来完成。

Kanzi graphics API 可以从任何线程安全调用。这与 OpenGL 系列 API 不同，后者要求所有调用都在线程特定的上下文中进行。Kanzi graphics OpenGL 后端提供了一个渲染线程，以满足该 API 的这一要求。

请记住，您不能在自定义 Kanzi 应用程序或插件中直接使用特定的图形 API，例如 OpenGL 或 Vulkan。请改用 Kanzi graphics API。

除后端之外，Kanzi graphics 还允许您配置多个层，以实现独立于后端的附加行为。每个 Kanzi graphics 函数调用在由后端处理之前，都会先依次经过层列表。Kanzi 提供以下层：

验证层报告违反预期 API 用法的情况。
Statistics 层包含一组关于 Kanzi graphics 的统计信息。

Graphics 对象¶

您可以使用相应的创建信息对象和 gfx::create 函数创建 graphics 对象。Graphics 对象通过特定 type 的句柄守卫对象来表示。这些守卫对象采用引用计数，因此当所有引用都被销毁时，对象本身会被加入销毁队列。

对象一旦创建，其定义便不可更改。例如，您无法调整缓冲区或图像的大小，而必须使用新的属性创建新对象。

对象	创建结构体	描述 (Description)
缓冲区	`gfx::BufferCreateInfo`	表示可位于 CPU 或 GPU 内存中的一块内存。通常用于存储 Uniforms、顶点或索引数据，以及其他通用用途。
图像 (Image)	`gfx::ImageCreateInfo`	表示可由着色器 (Shader) 采样的图像对象。
帧缓冲区	`gfx::FrameBufferCreateInfo`	表示可用作渲染目标 (Render Target) 的屏幕上或屏幕外帧缓冲区。
顶点输入状态	`gfx::VertexInputStateCreateInfo`	表示缓冲区中存储的顶点数据的布局。
深度模板状态	`gfx::DepthStencilStateCreateInfo`	表示一组关于如何使用深度或模板图像的配置选项。
混合状态	`gfx::BlendStateCreateInfo`	表示一组关于如何混合渲染管线 output 的配置选项。
光栅化状态	`gfx::RasterStateCreateInfo`	表示一组关于光栅化器行为的配置选项，例如填充模式、剔除模式和三角形拓扑。
采样器	`gfx::SamplerCreateInfo`	表示采样器对象，用于配置着色器如何对图像进行采样。
渲染资源集	`gfx::RenderResourceSetCreateInfo`	表示渲染管线所需的一组资源，例如缓冲区、图像和采样器。
计算资源集	`gfx::ComputeResourceSetCreateInfo`	表示计算管线所需的一组资源，例如缓冲区和图像。
着色器 (Shader)	`gfx::ShaderCreateInfo`	表示着色器程序，可以是顶点、片段、曲面细分、几何或计算着色器。这些着色器与其他状态对象组合在一起，构成完整的渲染管线或计算管线。
计算管线	`gfx::ComputePipelineCreateInfo`	表示计算程序。
渲染管线	`gfx::RenderPipelineCreateInfo`	表示一个渲染程序，其中包含一整套着色器、深度模板状态、混合状态、光栅状态、顶点输入状态以及渲染目标的描述。
渲染通道	`gfx::RenderPassCreateInfo`	表示一组渲染目标，以及这些目标在内存中的加载或存储方式。
命令缓冲区	`gfx::CommandBufferCreateInfo`	表示 CPU 内存中的一个区域，其中包含由 Kanzi 图形 API 执行的 Kanzi 图形命令。
GPU 栅栏	`gfx::GpuFenceCreateInfo`	表示一个同步对象，可用于让线程等待，直到命令缓冲区的特定部分执行完毕。

命令¶

命令记录在命令缓冲区中，并使用 gfx::processCommands 函数执行。已加载的后端以异步方式处理命令的执行。

命令	描述 (Description)
`gfx::CopyBufferCommand`	将内存从源缓冲区复制到目标缓冲区。
`gfx::CopyBufferToImageCommand`	将内存从源缓冲区复制到目标图像。
`gfx::CopyImageCommand`	将内容从源图像复制到目标图像。
`gfx::CopyImageToBufferCommand`	将内容从源图像复制到目标图像。
`gfx::CopySurfaceToBufferCommand`	将内容从屏幕帧缓冲区复制到目标缓冲区。
`gfx::BeginRenderPassCommand`	开始渲染到指定的渲染通道。
`gfx::EndRenderPassCommand`	结束上一个渲染通道的渲染。
`gfx::BeginRenderPipelineCommand`	附加一个渲染管线，供后续的绘制命令使用。
`gfx::EndRenderPipelineCommand`	结束对上一个渲染管线的使用。
`gfx::ConstantDataCommand`	更新常量 Uniform 数据，供后续的绘制命令使用。
`gfx::DrawCommand`	根据当前设置的资源绘制一定数量的三角形或实例。
`gfx::DrawIndirectCommand`	根据缓冲区的内容发出间接绘制。
`gfx::BeginComputePipelineCommand`	附加一个计算管线，供后续的调度命令使用。
`gfx::EndComputePipelineCommand`	结束对上一个计算管线的使用。
`gfx::DispatchCommand`	使用当前设置的资源分派计算操作。
`gfx::DispatchIndirectCommand`	根据缓冲的内容发出间接分派。
`gfx::PresentCommand`	通知平台层将屏幕上的表面呈现到屏幕。
`gfx::SignalGpuFenceCommand`	向 GPU Fence 对象发出信号。
`gfx::ResolveMultisampleImageCommand`	显式解析多重采样图像。
`gfx::GenerateMipmapsCommand`	为图像生成 mipmap。
`gfx::SetViewportCommand`	为后续渲染操作设置活动视口。
`gfx::SetScissorCommand`	为后续渲染操作设置活动裁剪区域。
`gfx::ClearCommand`	清除当前渲染通道中的渲染目标。
`gfx::SetLineWidthCommand`	设置使用基于线条的光栅化选项时的线宽。
`gfx::BindVertexInputCommand`	绑定一组顶点缓冲和一个可选的索引缓冲。
`gfx::SetUniformOffsetCommand`	设置后续操作在 Uniform 缓冲中使用的偏移量。
`gfx::BindRenderResourceSetCommand`	为后续渲染操作绑定一组渲染资源集 (Render Resource Sets)。
`gfx::BindComputeResourceSetCommand`	为后续计算操作绑定一组计算资源集 (Compute Resource Sets)。
`gfx::SubroutineCommand`	允许一个命令缓冲在执行返回到下一个命令之前调用第二个命令缓冲。

另请参阅¶

渲染 (Rendering)

Graphics