Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

RenderingDevice

继承: Object

用于处理现代低阶图形 API 的抽象。

描述

RenderingDevice 是用来使用 Vulkan 等现代低阶图形 API 的抽象。与(适用于 Godot 自有渲染子系统的)RenderingServer 相比,RenderingDevice 所处的层级更低,能够更加直接地使用底层图形 API。Godot 使用 RenderingDevice 来支持部分现代低阶图形 API,能够减少所需的重复代码。你也可以在自己的项目中使用 RenderingDevice,从而执行 RenderingServer 和高阶节点未暴露的功能,例如使用计算着色器。

启动时,Godot 会创建一个全局的 RenderingDevice,可以使用 RenderingServer.get_rendering_device 获取。这个全局的 RenderingDevice 进行的是屏幕绘图。

局部 RenderingDevice:你可以使用 RenderingServer.create_local_rendering_device 创建“次级”渲染设备,在单独的线程中进行渲染和 GPU 计算操作。

注意:使用 RenderingDevice 需要对 Vulkan、Direct3D 12、Metal 或 WebGPU 有中等水平的知识。这些图形 API 比 OpenGL 和 Direct3D 所处的层级更低,能够执行原本由图形驱动自己实现的功能。如果这个类中所使用的概念你理解起来有困难,请学习 Vulkan 教程Vulkan 指南。在尝试学习低阶图形 API 之前,建议先学习现代 OpenGL 或 Direct3D 11 相关的知识。

注意:使用无头模式运行或使用 Compatibility 渲染方法时,RenderingDevice 不可用。

教程

方法

void

barrier ( BitField<BarrierMask> from=32767, BitField<BarrierMask> to=32767 )

Error

buffer_clear ( RID buffer, int offset, int size_bytes, BitField<BarrierMask> post_barrier=32767 )

PackedByteArray

buffer_get_data ( RID buffer, int offset_bytes=0, int size_bytes=0 )

Error

buffer_update ( RID buffer, int offset, int size_bytes, PackedByteArray data, BitField<BarrierMask> post_barrier=32767 )

void

capture_timestamp ( String name )

void

compute_list_add_barrier ( int compute_list )

int

compute_list_begin ( bool allow_draw_overlap=false )

void

compute_list_bind_compute_pipeline ( int compute_list, RID compute_pipeline )

void

compute_list_bind_uniform_set ( int compute_list, RID uniform_set, int set_index )

void

compute_list_dispatch ( int compute_list, int x_groups, int y_groups, int z_groups )

void

compute_list_end ( BitField<BarrierMask> post_barrier=32767 )

void

compute_list_set_push_constant ( int compute_list, PackedByteArray buffer, int size_bytes )

RID

compute_pipeline_create ( RID shader, RDPipelineSpecializationConstant[] specialization_constants=[] )

bool

compute_pipeline_is_valid ( RID compute_pipeline )

RenderingDevice

create_local_device ( )

void

draw_command_begin_label ( String name, Color color )

void

draw_command_end_label ( )

void

draw_command_insert_label ( String name, Color color )

int

draw_list_begin ( RID framebuffer, InitialAction initial_color_action, FinalAction final_color_action, InitialAction initial_depth_action, FinalAction final_depth_action, PackedColorArray clear_color_values=PackedColorArray(), float clear_depth=1.0, int clear_stencil=0, Rect2 region=Rect2(0, 0, 0, 0), RID[] storage_textures=[] )

int

draw_list_begin_for_screen ( int screen=0, Color clear_color=Color(0, 0, 0, 1) )

PackedInt64Array

draw_list_begin_split ( RID framebuffer, int splits, InitialAction initial_color_action, FinalAction final_color_action, InitialAction initial_depth_action, FinalAction final_depth_action, PackedColorArray clear_color_values=PackedColorArray(), float clear_depth=1.0, int clear_stencil=0, Rect2 region=Rect2(0, 0, 0, 0), RID[] storage_textures=[] )

void

draw_list_bind_index_array ( int draw_list, RID index_array )

void

draw_list_bind_render_pipeline ( int draw_list, RID render_pipeline )

void

draw_list_bind_uniform_set ( int draw_list, RID uniform_set, int set_index )

void

draw_list_bind_vertex_array ( int draw_list, RID vertex_array )

void

draw_list_disable_scissor ( int draw_list )

void

draw_list_draw ( int draw_list, bool use_indices, int instances, int procedural_vertex_count=0 )

void

draw_list_enable_scissor ( int draw_list, Rect2 rect=Rect2(0, 0, 0, 0) )

void

draw_list_end ( BitField<BarrierMask> post_barrier=32767 )

void

draw_list_set_blend_constants ( int draw_list, Color color )

void

draw_list_set_push_constant ( int draw_list, PackedByteArray buffer, int size_bytes )

int

draw_list_switch_to_next_pass ( )

PackedInt64Array

draw_list_switch_to_next_pass_split ( int splits )

RID

framebuffer_create ( RID[] textures, int validate_with_format=-1, int view_count=1 )

RID

framebuffer_create_empty ( Vector2i size, TextureSamples samples=0, int validate_with_format=-1 )

RID

framebuffer_create_multipass ( RID[] textures, RDFramebufferPass[] passes, int validate_with_format=-1, int view_count=1 )

int

framebuffer_format_create ( RDAttachmentFormat[] attachments, int view_count=1 )

int

framebuffer_format_create_empty ( TextureSamples samples=0 )

int

framebuffer_format_create_multipass ( RDAttachmentFormat[] attachments, RDFramebufferPass[] passes, int view_count=1 )

TextureSamples

framebuffer_format_get_texture_samples ( int format, int render_pass=0 )

int

framebuffer_get_format ( RID framebuffer )

bool

framebuffer_is_valid ( RID framebuffer ) const

void

free_rid ( RID rid )

void

full_barrier ( )

int

get_captured_timestamp_cpu_time ( int index ) const

int

get_captured_timestamp_gpu_time ( int index ) const

String

get_captured_timestamp_name ( int index ) const

int

get_captured_timestamps_count ( ) const

int

get_captured_timestamps_frame ( ) const

String

get_device_name ( ) const

String

get_device_pipeline_cache_uuid ( ) const

String

get_device_vendor_name ( ) const

int

get_driver_resource ( DriverResource resource, RID rid, int index )

int

get_frame_delay ( ) const

int

get_memory_usage ( MemoryType type ) const

RID

index_array_create ( RID index_buffer, int index_offset, int index_count )

RID

index_buffer_create ( int size_indices, IndexBufferFormat format, PackedByteArray data=PackedByteArray(), bool use_restart_indices=false )

int

limit_get ( Limit limit ) const

RID

render_pipeline_create ( RID shader, int framebuffer_format, int vertex_format, RenderPrimitive primitive, RDPipelineRasterizationState rasterization_state, RDPipelineMultisampleState multisample_state, RDPipelineDepthStencilState stencil_state, RDPipelineColorBlendState color_blend_state, BitField<PipelineDynamicStateFlags> dynamic_state_flags=0, int for_render_pass=0, RDPipelineSpecializationConstant[] specialization_constants=[] )

bool

render_pipeline_is_valid ( RID render_pipeline )

RID

sampler_create ( RDSamplerState state )

bool

sampler_is_format_supported_for_filter ( DataFormat format, SamplerFilter sampler_filter ) const

int

screen_get_framebuffer_format ( ) const

int

screen_get_height ( int screen=0 ) const

int

screen_get_width ( int screen=0 ) const

void

set_resource_name ( RID id, String name )

PackedByteArray

shader_compile_binary_from_spirv ( RDShaderSPIRV spirv_data, String name="" )

RDShaderSPIRV

shader_compile_spirv_from_source ( RDShaderSource shader_source, bool allow_cache=true )

RID

shader_create_from_bytecode ( PackedByteArray binary_data, RID placeholder_rid=RID() )

RID

shader_create_from_spirv ( RDShaderSPIRV spirv_data, String name="" )

RID

shader_create_placeholder ( )

int

shader_get_vertex_input_attribute_mask ( RID shader )

RID

storage_buffer_create ( int size_bytes, PackedByteArray data=PackedByteArray(), BitField<StorageBufferUsage> usage=0 )

void

submit ( )

void

sync ( )

RID

texture_buffer_create ( int size_bytes, DataFormat format, PackedByteArray data=PackedByteArray() )

Error

texture_clear ( RID texture, Color color, int base_mipmap, int mipmap_count, int base_layer, int layer_count, BitField<BarrierMask> post_barrier=32767 )

Error

texture_copy ( RID from_texture, RID to_texture, Vector3 from_pos, Vector3 to_pos, Vector3 size, int src_mipmap, int dst_mipmap, int src_layer, int dst_layer, BitField<BarrierMask> post_barrier=32767 )

RID

texture_create ( RDTextureFormat format, RDTextureView view, PackedByteArray[] data=[] )

RID

texture_create_from_extension ( TextureType type, DataFormat format, TextureSamples samples, BitField<TextureUsageBits> usage_flags, int image, int width, int height, int depth, int layers )

RID

texture_create_shared ( RDTextureView view, RID with_texture )

RID

texture_create_shared_from_slice ( RDTextureView view, RID with_texture, int layer, int mipmap, int mipmaps=1, TextureSliceType slice_type=0 )

PackedByteArray

texture_get_data ( RID texture, int layer )

RDTextureFormat

texture_get_format ( RID texture )

int

texture_get_native_handle ( RID texture )

bool

texture_is_format_supported_for_usage ( DataFormat format, BitField<TextureUsageBits> usage_flags ) const

bool

texture_is_shared ( RID texture )

bool

texture_is_valid ( RID texture )

Error

texture_resolve_multisample ( RID from_texture, RID to_texture, BitField<BarrierMask> post_barrier=32767 )

Error

texture_update ( RID texture, int layer, PackedByteArray data, BitField<BarrierMask> post_barrier=32767 )

RID

uniform_buffer_create ( int size_bytes, PackedByteArray data=PackedByteArray() )

RID

uniform_set_create ( RDUniform[] uniforms, RID shader, int shader_set )

bool

uniform_set_is_valid ( RID uniform_set )

RID

vertex_array_create ( int vertex_count, int vertex_format, RID[] src_buffers, PackedInt64Array offsets=PackedInt64Array() )

RID

vertex_buffer_create ( int size_bytes, PackedByteArray data=PackedByteArray(), bool use_as_storage=false )

int

vertex_format_create ( RDVertexAttribute[] vertex_descriptions )


枚举

enum DeviceType:

DeviceType DEVICE_TYPE_OTHER = 0

渲染设备的类型与其他枚举值均不匹配,或者未知。

DeviceType DEVICE_TYPE_INTEGRATED_GPU = 1

渲染设备为集成 GPU,通常(但不一定)比独立 GPU(DEVICE_TYPE_DISCRETE_GPU)要慢。在 Android 和 iOS 上,渲染设备的类型始终为 DEVICE_TYPE_INTEGRATED_GPU

DeviceType DEVICE_TYPE_DISCRETE_GPU = 2

渲染设备为独立 GPU,通常(但不一定)比集成 GPU(DEVICE_TYPE_INTEGRATED_GPU)要快。

DeviceType DEVICE_TYPE_VIRTUAL_GPU = 3

渲染设备为虚拟环境中的模拟 GPU。通常比主机 GPU 要慢很多,这意味着独立 GPU 的预期性能等级大概与 DEVICE_TYPE_INTEGRATED_GPU 等价。使用虚拟机 GPU 穿透(例如 VFIO)时,设备类型不会被汇报为 DEVICE_TYPE_VIRTUAL_GPU。而是会汇报主机 GPU 的设备类型,就好像使用的不是模拟 GPU 一样。

DeviceType DEVICE_TYPE_CPU = 4

渲染设备由软件模拟提供(例如 Lavapipe 或 SwiftShader)。这是可用的渲染设备中最慢的一种;通常比 DEVICE_TYPE_INTEGRATED_GPU 要慢很多。

DeviceType DEVICE_TYPE_MAX = 5

代表 DeviceType 枚举的大小。


enum DriverResource:

DriverResource DRIVER_RESOURCE_VULKAN_DEVICE = 0

Vulkan 设备驱动资源。这是一种“全局”资源,会忽略传入的 RID

DriverResource DRIVER_RESOURCE_VULKAN_PHYSICAL_DEVICE = 1

物理设备(显卡)驱动资源。

DriverResource DRIVER_RESOURCE_VULKAN_INSTANCE = 2

Vulkan 实例驱动资源。

DriverResource DRIVER_RESOURCE_VULKAN_QUEUE = 3

Vulkan 队列驱动资源。

DriverResource DRIVER_RESOURCE_VULKAN_QUEUE_FAMILY_INDEX = 4

Vulkan 队列族索引驱动资源。

DriverResource DRIVER_RESOURCE_VULKAN_IMAGE = 5

Vulkan 图像驱动资源。

DriverResource DRIVER_RESOURCE_VULKAN_IMAGE_VIEW = 6

Vulkan 图像查看驱动资源。

DriverResource DRIVER_RESOURCE_VULKAN_IMAGE_NATIVE_TEXTURE_FORMAT = 7

Vulkan 图像原生纹理格式驱动资源。

DriverResource DRIVER_RESOURCE_VULKAN_SAMPLER = 8

Vulkan 采样器驱动资源。

DriverResource DRIVER_RESOURCE_VULKAN_DESCRIPTOR_SET = 9

Vulkan 描述符集驱动资源。

DriverResource DRIVER_RESOURCE_VULKAN_BUFFER = 10

Vulkan 缓冲驱动资源。

DriverResource DRIVER_RESOURCE_VULKAN_COMPUTE_PIPELINE = 11

Vulkan 计算管线驱动资源。

DriverResource DRIVER_RESOURCE_VULKAN_RENDER_PIPELINE = 12

Vulkan 渲染管线驱动资源。


enum DataFormat:

DataFormat DATA_FORMAT_R4G4_UNORM_PACK8 = 0

每通道 4 位的红、绿通道数据格式,紧缩在 8 个比特位中。取值均在 [0.0, 1.0] 的范围内。

注意:所有数据格式的更多信息可以在 Vulkan 规格说明的 Identification of formats 章节和 VkFormat 枚举中找到。

DataFormat DATA_FORMAT_R4G4B4A4_UNORM_PACK16 = 1

每通道 4 位的红、绿、蓝、Alpha 通道数据格式,紧缩在 16 个比特位中。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_B4G4R4A4_UNORM_PACK16 = 2

每通道 4 位的蓝、绿、红、Alpha 通道数据格式,紧缩在 16 个比特位中。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R5G6B5_UNORM_PACK16 = 3

红、绿、蓝通道数据格式,红占 5 位、绿占 6 位、蓝占 5 位,紧缩在 16 个比特位中。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_B5G6R5_UNORM_PACK16 = 4

蓝、绿、红通道数据格式,蓝占 5 位、绿占 6 位、红占 5 位,紧缩在 16 个比特位中。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R5G5B5A1_UNORM_PACK16 = 5

红、绿、蓝、Alpha 通道数据格式,红占 5 位、绿占 6 位、蓝占 5 位、Alpha 占 1 位,紧缩在 16 个比特位中。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_B5G5R5A1_UNORM_PACK16 = 6

蓝、绿、红、Alpha 通道数据格式,蓝占 5 位、绿占 6 位、红占 5 位、Alpha 占 1 位,紧缩在 16 个比特位中。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_A1R5G5B5_UNORM_PACK16 = 7

Alpha、红、绿、蓝通道数据格式,Alpha 占 1 位、红占 5 位、绿占 6 位、蓝占 5 位,紧缩在 16 个比特位中。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R8_UNORM = 8

每通道 8 位的无符号浮点数红通道数据格式,使用归一化的值。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R8_SNORM = 9

每通道 8 位的带符号浮点数红通道数据格式,使用归一化的值。取值均在 [-1.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R8_USCALED = 10

每通道 8 位的无符号浮点数红通道数据格式,使用缩放后的值(值从整数转换为浮点数)。取值均在 [0.0, 255.0] 的范围内。

DataFormat DATA_FORMAT_R8_SSCALED = 11

每通道 8 位的带符号浮点数红通道数据格式,使用缩放后的值(值从整数转换为浮点数)。取值均在 [-127.0, 127.0] 的范围内。

DataFormat DATA_FORMAT_R8_UINT = 12

每通道 8 位的无符号整数红通道数据格式。取值均在 [0, 255] 的范围内。

DataFormat DATA_FORMAT_R8_SINT = 13

每通道 8 位的带符号整数红通道数据格式。取值均在 [-127, 127] 的范围内。

DataFormat DATA_FORMAT_R8_SRGB = 14

每通道 8 位的无符号浮点数红通道数据格式,使用归一化的值、非线性 sRGB 编码。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R8G8_UNORM = 15

每通道 8 位的无符号浮点数红、绿通道数据格式,使用归一化的值。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R8G8_SNORM = 16

每通道 8 位的带符号浮点数红、绿通道数据格式,使用归一化的值。取值均在 [-1.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R8G8_USCALED = 17

每通道 8 位的无符号浮点数红、绿通道数据格式,使用缩放后的值(值从整数转换为浮点数)。取值均在 [0.0, 255.0] 的范围内。

DataFormat DATA_FORMAT_R8G8_SSCALED = 18

每通道 8 位的带符号浮点数红、绿通道数据格式,使用缩放后的值(值从整数转换为浮点数)。取值均在 [-127.0, 127.0] 的范围内。

DataFormat DATA_FORMAT_R8G8_UINT = 19

每通道 8 位的无符号整数红、绿通道数据格式。取值均在 [0, 255] 的范围内。

DataFormat DATA_FORMAT_R8G8_SINT = 20

每通道 8 位的带符号整数红、绿通道数据格式。取值均在 [-127, 127] 的范围内。

DataFormat DATA_FORMAT_R8G8_SRGB = 21

每通道 8 位的无符号浮点数红、绿通道数据格式,使用归一化的值、非线性 sRGB 编码。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R8G8B8_UNORM = 22

每通道 8 位的无符号浮点数红、绿、蓝通道数据格式,使用归一化的值。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R8G8B8_SNORM = 23

每通道 8 位的带符号浮点数红、绿、蓝通道数据格式,使用归一化的值。取值均在 [-1.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R8G8B8_USCALED = 24

每通道 8 位的无符号浮点数红、绿、蓝通道数据格式,使用缩放后的值(值从整数转换为浮点数)。取值均在 [0.0, 255.0] 的范围内。

DataFormat DATA_FORMAT_R8G8B8_SSCALED = 25

每通道 8 位的带符号浮点数红、绿、蓝通道数据格式,使用缩放后的值(值从整数转换为浮点数)。取值均在 [-127.0, 127.0] 的范围内。

DataFormat DATA_FORMAT_R8G8B8_UINT = 26

每通道 8 位的无符号整数红、绿、蓝通道数据格式。取值均在 [0, 255] 的范围内。

DataFormat DATA_FORMAT_R8G8B8_SINT = 27

每通道 8 位的带符号整数红、绿、蓝通道数据格式。取值均在 [-127, 127] 的范围内。

DataFormat DATA_FORMAT_R8G8B8_SRGB = 28

每通道 8 位的无符号浮点数红、绿、蓝通道数据格式,使用归一化的值、非线性 sRGB 编码。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_B8G8R8_UNORM = 29

每通道 8 位的无符号浮点数蓝、绿、红通道数据格式,使用归一化的值。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_B8G8R8_SNORM = 30

每通道 8 位的带符号浮点数蓝、绿、红通道数据格式,使用归一化的值。取值均在 [-1.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_B8G8R8_USCALED = 31

每通道 8 位的无符号浮点数蓝、绿、红通道数据格式,使用缩放后的值(值从整数转换为浮点数)。取值均在 [0.0, 255.0] 的范围内。

DataFormat DATA_FORMAT_B8G8R8_SSCALED = 32

每通道 8 位的带符号浮点数蓝、绿、红通道数据格式,使用缩放后的值(值从整数转换为浮点数)。取值均在 [-127.0, 127.0] 的范围内。

DataFormat DATA_FORMAT_B8G8R8_UINT = 33

每通道 8 位的无符号整数蓝、绿、红通道数据格式。取值均在 [0, 255] 的范围内。

DataFormat DATA_FORMAT_B8G8R8_SINT = 34

每通道 8 位的带符号整数蓝、绿、红通道数据格式。取值均在 [-127, 127] 的范围内。

DataFormat DATA_FORMAT_B8G8R8_SRGB = 35

每通道 8 位的无符号浮点数蓝、绿、红通道数据格式,使用归一化的值、非线性 sRGB 编码。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R8G8B8A8_UNORM = 36

每通道 8 位的无符号浮点数红、绿、蓝、Alpha 通道数据格式,使用归一化的值。取值均在 [0.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R8G8B8A8_SNORM = 37

每通道 8 位的带符号浮点数红、绿、蓝、Alpha 通道数据格式,使用归一化的值。取值均在 [-1.0, 1.0] 的范围内。

DataFormat DATA_FORMAT_R8G8B8A8_USCALED = 38

每通道 8 位的无符号浮点数红、绿、蓝、Alpha 通道数据格式,使用缩放后的值(值从整数转换为浮点数)。取值均在 [0.0, 255.0] 的范围内。

DataFormat DATA_FORMAT_R8G8B8A8_SSCALED = 39

每通道 8 位的带符号浮点数红、绿、蓝、Alpha 通道数据格式,使用缩放后的值(值从整数转换为浮点数)。取值均在 [-127.0, 127.0] 的范围内。

DataFormat DATA_FORMAT_R8G8B8A8_UINT = 40

每通道 8 位的无符号整数红、绿、蓝、Alpha 通道数据格式。取值均在 [0, 255] 的范围内。

DataFormat DATA_FORMAT_R8G8B8A8_SINT = 41

每通道 8 位的带符号整数红、绿、蓝、Alpha 通道数据格式。取值均在 [-127, 127] 的范围内。

DataFormat DATA_FORMAT_R8G8B8A8_SRGB = 42

每通道 8 位的无符号浮点数红、绿、蓝、Alpha 通道数据格式,使用归一化的值、非线性 sRGB 编码。取值均在 [0.0, 1.0] 的范围内。