Class RenderingDevice
Abstraction for working with modern low-level graphics APIs.
- Inheritance
-
RenderingDevice
Remarks
RenderingDevice is an abstraction for working with modern low-level graphics APIs such as Vulkan. Compared to RenderingServer (which works with Godot's own rendering subsystems), RenderingDevice is much lower-level and allows working more directly with the underlying graphics APIs. RenderingDevice is used in Godot to provide support for several modern low-level graphics APIs while reducing the amount of code duplication required. RenderingDevice can also be used in your own projects to perform things that are not exposed by RenderingServer or high-level nodes, such as using compute shaders.
On startup, Godot creates a global RenderingDevice which can be retrieved using get_rendering_device. This global RenderingDevice performs drawing to the screen.
Local RenderingDevices: Using create_local_rendering_device, you can create "secondary" rendering devices to perform drawing and GPU compute operations on separate threads.
Note: RenderingDevice assumes intermediate knowledge of modern graphics APIs such as Vulkan, Direct3D 12, Metal or WebGPU. These graphics APIs are lower-level than OpenGL or Direct3D 11, requiring you to perform what was previously done by the graphics driver itself. If you have difficulty understanding the concepts used in this class, follow the Vulkan Tutorial or Vulkan Guide. It's recommended to have existing modern OpenGL or Direct3D 11 knowledge before attempting to learn a low-level graphics API.
Note: RenderingDevice is not available when running in headless mode or when using the Compatibility rendering method.
See Also
Fields
INVALID_ID
Returned by functions that return an ID if a value is invalid.
const INVALID_ID = -1INVALID_FORMAT_ID
Returned by functions that return a format ID if a value is invalid.
const INVALID_FORMAT_ID = -1Methods
barrier(int, int)
This method does nothing.
void barrier(int from, int to)Parameters
buffer_clear(RID, int, int)
Clears the contents of the buffer, clearing size_bytes bytes, starting at offset.
Prints an error if:
the size isn't a multiple of four
the region specified by
offset+size_bytesexceeds the buffera draw list is currently active (created by RenderingDevice.draw_list_begin)
a compute list is currently active (created by compute_list_begin)
int buffer_clear(RID buffer, int offset, int size_bytes)Parameters
buffer_copy(RID, RID, int, int, int)
Copies size bytes from the src_buffer at src_offset into dst_buffer at dst_offset.
Prints an error if:
sizeexceeds the size of eithersrc_bufferordst_bufferat their corresponding offsetsa draw list is currently active (created by RenderingDevice.draw_list_begin)
a compute list is currently active (created by compute_list_begin)
int buffer_copy(RID src_buffer, RID dst_buffer, int src_offset, int dst_offset, int size)Parameters
buffer_get_data(RID, int, int)
Returns a copy of the data of the specified buffer, optionally offset_bytes and size_bytes can be set to copy only a portion of the buffer.
Note: This method will block the GPU from working until the data is retrieved. Refer to RenderingDevice.buffer_get_data_async for an alternative that returns the data in more performant way.
PackedByteArray buffer_get_data(RID buffer, int offset_bytes, int size_bytes)Parameters
buffer_get_data_async(RID, Callable, int, int)
Asynchronous version of RenderingDevice.buffer_get_data. RenderingDevice will call callback in a certain amount of frames with the data the buffer had at the time of the request.
Note: At the moment, the delay corresponds to the amount of frames specified by rendering/rendering_device/vsync/frame_queue_size.
Note: Downloading large buffers can have a prohibitive cost for real-time even when using the asynchronous method due to hardware bandwidth limitations. When dealing with large resources, you can adjust settings such as rendering/rendering_device/staging_buffer/block_size_kb to improve the transfer speed at the cost of extra memory.
func _buffer_get_data_callback(array):
value = array.decode_u32(0)
...
rd.buffer_get_data_async(buffer, _buffer_get_data_callback)
int buffer_get_data_async(RID buffer, Callable callback, int offset_bytes, int size_bytes)Parameters
buffer_get_device_address(RID)
Returns the address of the given buffer which can be passed to shaders in any way to access underlying data. Buffer must have been created with this feature enabled.
Note: You must check that the GPU supports this functionality by calling RenderingDevice.has_feature with RenderingDevice.SUPPORTS_BUFFER_DEVICE_ADDRESS as a parameter.
int buffer_get_device_address(RID buffer)Parameters
bufferRID
buffer_update(RID, int, int, PackedByteArray)
Updates a region of size_bytes bytes, starting at offset, in the buffer, with the specified data.
Prints an error if:
the region specified by
offset+size_bytesexceeds the buffera draw list is currently active (created by RenderingDevice.draw_list_begin)
a compute list is currently active (created by compute_list_begin)
int buffer_update(RID buffer, int offset, int size_bytes, PackedByteArray data)Parameters
bufferRIDoffsetintsize_bytesintdataPackedByteArray
capture_timestamp(String)
Creates a timestamp marker with the specified name. This is used for performance reporting with the RenderingDevice.get_captured_timestamp_cpu_time, RenderingDevice.get_captured_timestamp_gpu_time and RenderingDevice.get_captured_timestamp_name methods.
void capture_timestamp(String name)Parameters
nameString
compute_list_add_barrier(int)
Raises a Vulkan compute barrier in the specified compute_list.
void compute_list_add_barrier(int compute_list)Parameters
compute_listint
compute_list_begin
Starts a list of compute commands created with the compute_* methods. The returned value should be passed to other compute_list_* functions.
Multiple compute lists cannot be created at the same time; you must finish the previous compute list first using compute_list_end.
A simple compute operation might look like this (code is not a complete example):
var rd = RenderingDevice.new()
var compute_list = rd.compute_list_begin()
rd.compute_list_bind_compute_pipeline(compute_list, compute_shader_dilate_pipeline)
rd.compute_list_bind_uniform_set(compute_list, compute_base_uniform_set, 0)
rd.compute_list_bind_uniform_set(compute_list, dilate_uniform_set, 1)
for i in atlas_slices:
rd.compute_list_set_push_constant(compute_list, push_constant, push_constant.size())
rd.compute_list_dispatch(compute_list, group_size.x, group_size.y, group_size.z)
# No barrier, let them run all together.
rd.compute_list_end()
int compute_list_begincompute_list_bind_compute_pipeline(int, RID)
Tells the GPU what compute pipeline to use when processing the compute list. If the shader has changed since the last time this function was called, Godot will unbind all descriptor sets and will re-bind them inside RenderingDevice.compute_list_dispatch.
void compute_list_bind_compute_pipeline(int compute_list, RID compute_pipeline)Parameters
compute_list_bind_uniform_set(int, RID, int)
Binds the uniform_set to this compute_list. Godot ensures that all textures in the uniform set have the correct Vulkan access masks. If Godot had to change access masks of textures, it will raise a Vulkan image memory barrier.
void compute_list_bind_uniform_set(int compute_list, RID uniform_set, int set_index)Parameters
compute_list_dispatch(int, int, int, int)
Submits the compute list for processing on the GPU. This is the compute equivalent to RenderingDevice.draw_list_draw.
void compute_list_dispatch(int compute_list, int x_groups, int y_groups, int z_groups)Parameters
compute_list_dispatch_indirect(int, RID, int)
Submits the compute list for processing on the GPU with the given group counts stored in the buffer at offset. Buffer must have been created with RenderingDevice.STORAGE_BUFFER_USAGE_DISPATCH_INDIRECT flag.
void compute_list_dispatch_indirect(int compute_list, RID buffer, int offset)Parameters
compute_list_end
Finishes a list of compute commands created with the compute_* methods.
void compute_list_endcompute_list_set_push_constant(int, PackedByteArray, int)
Sets the push constant data to buffer for the specified compute_list. The shader determines how this binary data is used. The buffer's size in bytes must also be specified in size_bytes (this can be obtained by calling the size method on the passed buffer).
void compute_list_set_push_constant(int compute_list, PackedByteArray buffer, int size_bytes)Parameters
compute_listintbufferPackedByteArraysize_bytesint
compute_pipeline_create(RID, RDPipelineSpecializationConstant[])
Creates a new compute pipeline. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID compute_pipeline_create(RID shader, RDPipelineSpecializationConstant[] specialization_constants)Parameters
shaderRIDspecialization_constantsRDPipelineSpecializationConstant[]
compute_pipeline_is_valid(RID)
Returns true if the compute pipeline specified by the compute_pipeline RID is valid, false otherwise.
bool compute_pipeline_is_valid(RID compute_pipeline)Parameters
compute_pipelineRID
create_local_device
Create a new local RenderingDevice. This is most useful for performing compute operations on the GPU independently from the rest of the engine.
RenderingDevice create_local_devicedraw_command_begin_label(String, Color)
Create a command buffer debug label region that can be displayed in third-party tools such as RenderDoc. All regions must be ended with a draw_command_end_label call. When viewed from the linear series of submissions to a single queue, calls to RenderingDevice.draw_command_begin_label and draw_command_end_label must be matched and balanced.
The VK_EXT_DEBUG_UTILS_EXTENSION_NAME Vulkan extension must be available and enabled for command buffer debug label region to work. See also draw_command_end_label.
void draw_command_begin_label(String name, Color color)Parameters
draw_command_end_label
Ends the command buffer debug label region started by a RenderingDevice.draw_command_begin_label call.
void draw_command_end_labeldraw_command_insert_label(String, Color)
This method does nothing.
void draw_command_insert_label(String name, Color color)Parameters
draw_list_begin(RID, int, PackedColorArray, float, int, Rect2, int)
Starts a list of raster drawing commands created with the draw_* methods. The returned value should be passed to other draw_list_* functions.
Multiple draw lists cannot be created at the same time; you must finish the previous draw list first using draw_list_end.
A simple drawing operation might look like this (code is not a complete example):
var rd = RenderingDevice.new()
var clear_colors = PackedColorArray([Color(0, 0, 0, 0), Color(0, 0, 0, 0), Color(0, 0, 0, 0)])
var draw_list = rd.draw_list_begin(framebuffers[i], RenderingDevice.CLEAR_COLOR_ALL, clear_colors, true, 1.0f, true, 0, Rect2(), RenderingDevice.OPAQUE_PASS)
# Draw opaque.
rd.draw_list_bind_render_pipeline(draw_list, raster_pipeline)
rd.draw_list_bind_uniform_set(draw_list, raster_base_uniform, 0)
rd.draw_list_set_push_constant(draw_list, raster_push_constant, raster_push_constant.size())
rd.draw_list_draw(draw_list, false, 1, slice_triangle_count[i] * 3)
# Draw wire.
rd.draw_list_bind_render_pipeline(draw_list, raster_pipeline_wire)
rd.draw_list_bind_uniform_set(draw_list, raster_base_uniform, 0)
rd.draw_list_set_push_constant(draw_list, raster_push_constant, raster_push_constant.size())
rd.draw_list_draw(draw_list, false, 1, slice_triangle_count[i] * 3)
rd.draw_list_end()
The draw_flags indicates if the texture attachments of the framebuffer should be cleared or ignored. Only one of the two flags can be used for each individual attachment. Ignoring an attachment means that any contents that existed before the draw list will be completely discarded, reducing the memory bandwidth used by the render pass but producing garbage results if the pixels aren't replaced. The default behavior allows the engine to figure out the right operation to use if the texture is discardable, which can result in increased performance. See RDTextureFormat or RenderingDevice.texture_set_discardable.
The breadcrumb parameter can be an arbitrary 32-bit integer that is useful to diagnose GPU crashes. If Godot is built in dev or debug mode; when the GPU crashes Godot will dump all shaders that were being executed at the time of the crash and the breadcrumb is useful to diagnose what passes did those shaders belong to.
It does not affect rendering behavior and can be set to 0. It is recommended to use BreadcrumbMarker enumerations for consistency but it's not required. It is also possible to use bitwise operations to add extra data. e.g.
rd.draw_list_begin(fb[i], RenderingDevice.CLEAR_COLOR_ALL, clear_colors, true, 1.0f, true, 0, Rect2(), RenderingDevice.OPAQUE_PASS | 5)
int draw_list_begin(RID framebuffer, int draw_flags, PackedColorArray clear_color_values, float clear_depth_value, int clear_stencil_value, Rect2 region, int breadcrumb)Parameters
framebufferRIDdraw_flagsintclear_color_valuesPackedColorArrayclear_depth_valuefloatclear_stencil_valueintregionRect2breadcrumbint
draw_list_begin_for_screen(int, Color)
High-level variant of RenderingDevice.draw_list_begin, with the parameters automatically being adjusted for drawing onto the window specified by the screen ID.
Note: Cannot be used with local RenderingDevices, as these don't have a screen. If called on a local RenderingDevice, RenderingDevice.draw_list_begin_for_screen returns INVALID_ID.
int draw_list_begin_for_screen(int screen, Color clear_color)Parameters
draw_list_begin_split(RID, int, int, int, int, int, PackedColorArray, float, int, Rect2, RID[])
This method does nothing and always returns an empty PackedInt64Array.
PackedInt64Array draw_list_begin_split(RID framebuffer, int splits, int initial_color_action, int final_color_action, int initial_depth_action, int final_depth_action, PackedColorArray clear_color_values, float clear_depth, int clear_stencil, Rect2 region, RID[] storage_textures)Parameters
framebufferRIDsplitsintinitial_color_actionintfinal_color_actionintinitial_depth_actionintfinal_depth_actionintclear_color_valuesPackedColorArrayclear_depthfloatclear_stencilintregionRect2storage_texturesRID[]
draw_list_bind_index_array(int, RID)
Binds index_array to the specified draw_list.
void draw_list_bind_index_array(int draw_list, RID index_array)Parameters
draw_list_bind_render_pipeline(int, RID)
Binds render_pipeline to the specified draw_list.
void draw_list_bind_render_pipeline(int draw_list, RID render_pipeline)Parameters
draw_list_bind_uniform_set(int, RID, int)
Binds uniform_set to the specified draw_list. A set_index must also be specified, which is an identifier starting from 0 that must match the one expected by the draw list.
void draw_list_bind_uniform_set(int draw_list, RID uniform_set, int set_index)Parameters
draw_list_bind_vertex_array(int, RID)
Binds vertex_array to the specified draw_list.
void draw_list_bind_vertex_array(int draw_list, RID vertex_array)Parameters
draw_list_disable_scissor(int)
Removes and disables the scissor rectangle for the specified draw_list. See also RenderingDevice.draw_list_enable_scissor.
void draw_list_disable_scissor(int draw_list)Parameters
draw_listint
draw_list_draw(int, bool, int, int)
Submits draw_list for rendering on the GPU. This is the raster equivalent to RenderingDevice.compute_list_dispatch.
void draw_list_draw(int draw_list, bool use_indices, int instances, int procedural_vertex_count)Parameters
draw_list_draw_indirect(int, bool, RID, int, int, int)
Submits draw_list for rendering on the GPU with the given parameters stored in the buffer at offset. Parameters being integers: vertex count, instance count, first vertex, first instance. And when using indices: index count, instance count, first index, vertex offset, first instance. Buffer must have been created with RenderingDevice.STORAGE_BUFFER_USAGE_DISPATCH_INDIRECT flag.
void draw_list_draw_indirect(int draw_list, bool use_indices, RID buffer, int offset, int draw_count, int stride)Parameters
draw_list_enable_scissor(int, Rect2)
Creates a scissor rectangle and enables it for the specified draw_list. Scissor rectangles are used for clipping by discarding fragments that fall outside a specified rectangular portion of the screen. See also RenderingDevice.draw_list_disable_scissor.
Note: The specified rect is automatically intersected with the screen's dimensions, which means it cannot exceed the screen's dimensions.
void draw_list_enable_scissor(int draw_list, Rect2 rect)Parameters
draw_list_end
Finishes a list of raster drawing commands created with the draw_* methods.
void draw_list_enddraw_list_set_blend_constants(int, Color)
Sets blend constants for the specified draw_list to color. Blend constants are used only if the graphics pipeline is created with RenderingDevice.DYNAMIC_STATE_BLEND_CONSTANTS flag set.
void draw_list_set_blend_constants(int draw_list, Color color)Parameters
draw_list_set_push_constant(int, PackedByteArray, int)
Sets the push constant data to buffer for the specified draw_list. The shader determines how this binary data is used. The buffer's size in bytes must also be specified in size_bytes (this can be obtained by calling the size method on the passed buffer).
void draw_list_set_push_constant(int draw_list, PackedByteArray buffer, int size_bytes)Parameters
draw_listintbufferPackedByteArraysize_bytesint
draw_list_switch_to_next_pass
Switches to the next draw pass.
int draw_list_switch_to_next_passdraw_list_switch_to_next_pass_split(int)
This method does nothing and always returns an empty PackedInt64Array.
PackedInt64Array draw_list_switch_to_next_pass_split(int splits)Parameters
splitsint
framebuffer_create(RID[], int, int)
Creates a new framebuffer. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID framebuffer_create(RID[] textures, int validate_with_format, int view_count)Parameters
framebuffer_create_empty(Vector2i, int, int)
Creates a new empty framebuffer. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID framebuffer_create_empty(Vector2i size, int samples, int validate_with_format)Parameters
framebuffer_create_multipass(RID[], RDFramebufferPass[], int, int)
Creates a new multipass framebuffer. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID framebuffer_create_multipass(RID[] textures, RDFramebufferPass[] passes, int validate_with_format, int view_count)Parameters
framebuffer_format_create(RDAttachmentFormat[], int)
Creates a new framebuffer format with the specified attachments and view_count. Returns the new framebuffer's unique framebuffer format ID.
If view_count is greater than or equal to 2, enables multiview which is used for VR rendering. This requires support for the Vulkan multiview extension.
int framebuffer_format_create(RDAttachmentFormat[] attachments, int view_count)Parameters
attachmentsRDAttachmentFormat[]view_countint
framebuffer_format_create_empty(int)
Creates a new empty framebuffer format with the specified number of samples and returns its ID.
int framebuffer_format_create_empty(int samples)Parameters
samplesint
framebuffer_format_create_multipass(RDAttachmentFormat[], RDFramebufferPass[], int)
Creates a multipass framebuffer format with the specified attachments, passes and view_count and returns its ID. If view_count is greater than or equal to 2, enables multiview which is used for VR rendering. This requires support for the Vulkan multiview extension.
int framebuffer_format_create_multipass(RDAttachmentFormat[] attachments, RDFramebufferPass[] passes, int view_count)Parameters
attachmentsRDAttachmentFormat[]passesRDFramebufferPass[]view_countint
framebuffer_format_get_texture_samples(int, int)
Returns the number of texture samples used for the given framebuffer format ID (returned by RenderingDevice.framebuffer_get_format).
int framebuffer_format_get_texture_samples(int format, int render_pass)Parameters
framebuffer_get_format(RID)
Returns the format ID of the framebuffer specified by the framebuffer RID. This ID is guaranteed to be unique for the same formats and does not need to be freed.
int framebuffer_get_format(RID framebuffer)Parameters
framebufferRID
framebuffer_is_valid(RID)
Qualifiers: const
Returns true if the framebuffer specified by the framebuffer RID is valid, false otherwise.
bool framebuffer_is_valid(RID framebuffer)Parameters
framebufferRID
free_rid(RID)
Tries to free an object in the RenderingDevice. To avoid memory leaks, this should be called after using an object as memory management does not occur automatically when using RenderingDevice directly.
void free_rid(RID rid)Parameters
ridRID
full_barrier
This method does nothing.
void full_barrierget_captured_timestamp_cpu_time(int)
Qualifiers: const
Returns the timestamp in CPU time for the rendering step specified by index (in microseconds since the engine started). See also RenderingDevice.get_captured_timestamp_gpu_time and RenderingDevice.capture_timestamp.
int get_captured_timestamp_cpu_time(int index)Parameters
indexint
get_captured_timestamp_gpu_time(int)
Qualifiers: const
Returns the timestamp in GPU time for the rendering step specified by index (in microseconds since the engine started). See also RenderingDevice.get_captured_timestamp_cpu_time and RenderingDevice.capture_timestamp.
int get_captured_timestamp_gpu_time(int index)Parameters
indexint
get_captured_timestamp_name(int)
Qualifiers: const
Returns the timestamp's name for the rendering step specified by index. See also RenderingDevice.capture_timestamp.
String get_captured_timestamp_name(int index)Parameters
indexint
get_captured_timestamps_count
Qualifiers: const
Returns the total number of timestamps (rendering steps) available for profiling.
int get_captured_timestamps_countget_captured_timestamps_frame
Qualifiers: const
Returns the index of the last frame rendered that has rendering timestamps available for querying.
int get_captured_timestamps_frameget_device_allocation_count
Qualifiers: const
Returns how many allocations the GPU has performed for internal driver structures.
This is only used by Vulkan in debug builds and can return 0 when this information is not tracked or unknown.
int get_device_allocation_countget_device_allocs_by_object_type(int)
Qualifiers: const
Same as get_device_allocation_count but filtered for a given object type.
The type argument must be in range [0; get_tracked_object_type_count - 1]. If get_tracked_object_type_count is 0, then type argument is ignored and always returns 0.
This is only used by Vulkan in debug builds and can return 0 when this information is not tracked or unknown.
int get_device_allocs_by_object_type(int type)Parameters
typeint
get_device_memory_by_object_type(int)
Qualifiers: const
Same as get_device_total_memory but filtered for a given object type.
The type argument must be in range [0; get_tracked_object_type_count - 1]. If get_tracked_object_type_count is 0, then type argument is ignored and always returns 0.
This is only used by Vulkan in debug builds and can return 0 when this information is not tracked or unknown.
int get_device_memory_by_object_type(int type)Parameters
typeint
get_device_name
Qualifiers: const
Returns the name of the video adapter (e.g. "GeForce GTX 1080/PCIe/SSE2"). Equivalent to get_video_adapter_name. See also get_device_vendor_name.
String get_device_nameget_device_pipeline_cache_uuid
Qualifiers: const
Returns the universally unique identifier for the pipeline cache. This is used to cache shader files on disk, which avoids shader recompilations on subsequent engine runs. This UUID varies depending on the graphics card model, but also the driver version. Therefore, updating graphics drivers will invalidate the shader cache.
String get_device_pipeline_cache_uuidget_device_total_memory
Qualifiers: const
Returns how much bytes the GPU is using.
This is only used by Vulkan in debug builds and can return 0 when this information is not tracked or unknown.
int get_device_total_memoryget_device_vendor_name
Qualifiers: const
Returns the vendor of the video adapter (e.g. "NVIDIA Corporation"). Equivalent to get_video_adapter_vendor. See also get_device_name.
String get_device_vendor_nameget_driver_allocation_count
Qualifiers: const
Returns how many allocations the GPU driver has performed for internal driver structures.
This is only used by Vulkan in debug builds and can return 0 when this information is not tracked or unknown.
int get_driver_allocation_countget_driver_allocs_by_object_type(int)
Qualifiers: const
Same as get_driver_allocation_count but filtered for a given object type.
The type argument must be in range [0; get_tracked_object_type_count - 1]. If get_tracked_object_type_count is 0, then type argument is ignored and always returns 0.
This is only used by Vulkan in debug builds and can return 0 when this information is not tracked or unknown.
int get_driver_allocs_by_object_type(int type)Parameters
typeint
get_driver_and_device_memory_report
Qualifiers: const
Returns string report in CSV format using the following methods:
RenderingDevice.get_tracked_object_name
RenderingDevice.get_driver_memory_by_object_type
RenderingDevice.get_driver_allocs_by_object_type
RenderingDevice.get_device_memory_by_object_type
RenderingDevice.get_device_allocs_by_object_type
This is only used by Vulkan in debug builds. Godot must also be started with the --extra-gpu-memory-tracking command line argument.
String get_driver_and_device_memory_reportget_driver_memory_by_object_type(int)
Qualifiers: const
Same as get_driver_total_memory but filtered for a given object type.
The type argument must be in range [0; get_tracked_object_type_count - 1]. If get_tracked_object_type_count is 0, then type argument is ignored and always returns 0.
This is only used by Vulkan in debug builds and can return 0 when this information is not tracked or unknown.
int get_driver_memory_by_object_type(int type)Parameters
typeint
get_driver_resource(int, RID, int)
Returns the unique identifier of the driver resource for the specified rid. Some driver resource types ignore the specified rid (see DriverResource descriptions). index is always ignored but must be specified anyway.
int get_driver_resource(int resource, RID rid, int index)Parameters
get_driver_total_memory
Qualifiers: const
Returns how much bytes the GPU driver is using for internal driver structures.
This is only used by Vulkan in debug builds and can return 0 when this information is not tracked or unknown.
int get_driver_total_memoryget_frame_delay
Qualifiers: const
Returns the frame count kept by the graphics API. Higher values result in higher input lag, but with more consistent throughput. For the main RenderingDevice, frames are cycled (usually 3 with triple-buffered V-Sync enabled). However, local RenderingDevices only have 1 frame.
int get_frame_delayget_memory_usage(int)
Qualifiers: const
Returns the memory usage in bytes corresponding to the given type. When using Vulkan, these statistics are calculated by Vulkan Memory Allocator.
int get_memory_usage(int type)Parameters
typeint
get_perf_report
Qualifiers: const
Returns a string with a performance report from the past frame. Updates every frame.
String get_perf_reportget_tracked_object_name(int)
Qualifiers: const
Returns the name of the type of object for the given type_index. This value must be in range [0; get_tracked_object_type_count - 1]. If get_tracked_object_type_count is 0, then type argument is ignored and always returns the same string.
The return value is important because it gives meaning to the types passed to RenderingDevice.get_driver_memory_by_object_type, RenderingDevice.get_driver_allocs_by_object_type, RenderingDevice.get_device_memory_by_object_type, and RenderingDevice.get_device_allocs_by_object_type. Examples of strings it can return (not exhaustive):
DEVICE_MEMORY
PIPELINE_CACHE
SWAPCHAIN_KHR
COMMAND_POOL
Thus if e.g. get_tracked_object_name(5) returns "COMMAND_POOL", then get_device_memory_by_object_type(5) returns the bytes used by the GPU for command pools.
This is only used by Vulkan in debug builds. Godot must also be started with the --extra-gpu-memory-tracking command line argument.
String get_tracked_object_name(int type_index)Parameters
type_indexint
get_tracked_object_type_count
Qualifiers: const
Returns how many types of trackable objects are.
This is only used by Vulkan in debug builds. Godot must also be started with the --extra-gpu-memory-tracking command line argument.
int get_tracked_object_type_counthas_feature(int)
Qualifiers: const
Returns true if the feature is supported by the GPU.
bool has_feature(int feature)Parameters
featureint
index_array_create(RID, int, int)
Creates a new index array. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID index_array_create(RID index_buffer, int index_offset, int index_count)Parameters
index_buffer_create(int, int, PackedByteArray, bool, int)
Creates a new index buffer. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID index_buffer_create(int size_indices, int format, PackedByteArray data, bool use_restart_indices, int creation_bits)Parameters
size_indicesintformatintdataPackedByteArrayuse_restart_indicesboolcreation_bitsint
limit_get(int)
Qualifiers: const
Returns the value of the specified limit. This limit varies depending on the current graphics hardware (and sometimes the driver version). If the given limit is exceeded, rendering errors will occur.
Limits for various graphics hardware can be found in the Vulkan Hardware Database.
int limit_get(int limit)Parameters
limitint
render_pipeline_create(RID, int, int, int, RDPipelineRasterizationState, RDPipelineMultisampleState, RDPipelineDepthStencilState, RDPipelineColorBlendState, int, int, RDPipelineSpecializationConstant[])
Creates a new render pipeline. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID render_pipeline_create(RID shader, int framebuffer_format, int vertex_format, int primitive, RDPipelineRasterizationState rasterization_state, RDPipelineMultisampleState multisample_state, RDPipelineDepthStencilState stencil_state, RDPipelineColorBlendState color_blend_state, int dynamic_state_flags, int for_render_pass, RDPipelineSpecializationConstant[] specialization_constants)Parameters
shaderRIDframebuffer_formatintvertex_formatintprimitiveintrasterization_stateRDPipelineRasterizationStatemultisample_stateRDPipelineMultisampleStatestencil_stateRDPipelineDepthStencilStatecolor_blend_stateRDPipelineColorBlendStatedynamic_state_flagsintfor_render_passintspecialization_constantsRDPipelineSpecializationConstant[]
render_pipeline_is_valid(RID)
Returns true if the render pipeline specified by the render_pipeline RID is valid, false otherwise.
bool render_pipeline_is_valid(RID render_pipeline)Parameters
render_pipelineRID
sampler_create(RDSamplerState)
Creates a new sampler. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID sampler_create(RDSamplerState state)Parameters
stateRDSamplerState
sampler_is_format_supported_for_filter(int, int)
Qualifiers: const
Returns true if implementation supports using a texture of format with the given sampler_filter.
bool sampler_is_format_supported_for_filter(int format, int sampler_filter)Parameters
screen_get_framebuffer_format(int)
Qualifiers: const
Returns the framebuffer format of the given screen.
Note: Only the main RenderingDevice returned by get_rendering_device has a format. If called on a local RenderingDevice, this method prints an error and returns INVALID_ID.
int screen_get_framebuffer_format(int screen)Parameters
screenint
screen_get_height(int)
Qualifiers: const
Returns the window height matching the graphics API context for the given window ID (in pixels). Despite the parameter being named screen, this returns the window size. See also RenderingDevice.screen_get_width.
Note: Only the main RenderingDevice returned by get_rendering_device has a height. If called on a local RenderingDevice, this method prints an error and returns INVALID_ID.
int screen_get_height(int screen)Parameters
screenint
screen_get_width(int)
Qualifiers: const
Returns the window width matching the graphics API context for the given window ID (in pixels). Despite the parameter being named screen, this returns the window size. See also RenderingDevice.screen_get_height.
Note: Only the main RenderingDevice returned by get_rendering_device has a width. If called on a local RenderingDevice, this method prints an error and returns INVALID_ID.
int screen_get_width(int screen)Parameters
screenint
set_resource_name(RID, String)
Sets the resource name for id to name. This is used for debugging with third-party tools such as RenderDoc.
The following types of resources can be named: texture, sampler, vertex buffer, index buffer, uniform buffer, texture buffer, storage buffer, uniform set buffer, shader, render pipeline and compute pipeline. Framebuffers cannot be named. Attempting to name an incompatible resource type will print an error.
Note: Resource names are only set when the engine runs in verbose mode (is_stdout_verbose = true), or when using an engine build compiled with the dev_mode=yes SCons option. The graphics driver must also support the VK_EXT_DEBUG_UTILS_EXTENSION_NAME Vulkan extension for named resources to work.
void set_resource_name(RID id, String name)Parameters
shader_compile_binary_from_spirv(RDShaderSPIRV, String)
Compiles a binary shader from spirv_data and returns the compiled binary data as a PackedByteArray. This compiled shader is specific to the GPU model and driver version used; it will not work on different GPU models or even different driver versions. See also RenderingDevice.shader_compile_spirv_from_source.
name is an optional human-readable name that can be given to the compiled shader for organizational purposes.
PackedByteArray shader_compile_binary_from_spirv(RDShaderSPIRV spirv_data, String name)Parameters
spirv_dataRDShaderSPIRVnameString
shader_compile_spirv_from_source(RDShaderSource, bool)
Compiles a SPIR-V from the shader source code in shader_source and returns the SPIR-V as a RDShaderSPIRV. This intermediate language shader is portable across different GPU models and driver versions, but cannot be run directly by GPUs until compiled into a binary shader using RenderingDevice.shader_compile_binary_from_spirv.
If allow_cache is true, make use of the shader cache generated by Godot. This avoids a potentially lengthy shader compilation step if the shader is already in cache. If allow_cache is false, Godot's shader cache is ignored and the shader will always be recompiled.
RDShaderSPIRV shader_compile_spirv_from_source(RDShaderSource shader_source, bool allow_cache)Parameters
shader_sourceRDShaderSourceallow_cachebool
shader_create_from_bytecode(PackedByteArray, RID)
Creates a new shader instance from a binary compiled shader. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method. See also RenderingDevice.shader_compile_binary_from_spirv and RenderingDevice.shader_create_from_spirv.
RID shader_create_from_bytecode(PackedByteArray binary_data, RID placeholder_rid)Parameters
binary_dataPackedByteArrayplaceholder_ridRID
shader_create_from_spirv(RDShaderSPIRV, String)
Creates a new shader instance from SPIR-V intermediate code. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method. See also RenderingDevice.shader_compile_spirv_from_source and RenderingDevice.shader_create_from_bytecode.
RID shader_create_from_spirv(RDShaderSPIRV spirv_data, String name)Parameters
spirv_dataRDShaderSPIRVnameString
shader_create_placeholder
Create a placeholder RID by allocating an RID without initializing it for use in RenderingDevice.shader_create_from_bytecode. This allows you to create an RID for a shader and pass it around, but defer compiling the shader to a later time.
RID shader_create_placeholdershader_get_vertex_input_attribute_mask(RID)
Returns the internal vertex input mask. Internally, the vertex input mask is an unsigned integer consisting of the locations (specified in GLSL via. layout(location = ...)) of the input variables (specified in GLSL by the in keyword).
int shader_get_vertex_input_attribute_mask(RID shader)Parameters
shaderRID
storage_buffer_create(int, PackedByteArray, int, int)
Creates a storage buffer with the specified data and usage. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID storage_buffer_create(int size_bytes, PackedByteArray data, int usage, int creation_bits)Parameters
size_bytesintdataPackedByteArrayusageintcreation_bitsint
submit
Pushes the frame setup and draw command buffers then marks the local device as currently processing (which allows calling sync).
Note: Only available in local RenderingDevices.
void submitsync
Forces a synchronization between the CPU and GPU, which may be required in certain cases. Only call this when needed, as CPU-GPU synchronization has a performance cost.
Note: Only available in local RenderingDevices.
void synctexture_buffer_create(int, int, PackedByteArray)
Creates a new texture buffer. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID texture_buffer_create(int size_bytes, int format, PackedByteArray data)Parameters
size_bytesintformatintdataPackedByteArray
texture_clear(RID, Color, int, int, int, int)
Clears the specified texture by replacing all of its pixels with the specified color. base_mipmap and mipmap_count determine which mipmaps of the texture are affected by this clear operation, while base_layer and layer_count determine which layers of a 3D texture (or texture array) are affected by this clear operation. For 2D textures (which only have one layer by design), base_layer must be 0 and layer_count must be 1.
Note: texture can't be cleared while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to RenderingDevice.FINAL_ACTION_CONTINUE) to clear this texture.
int texture_clear(RID texture, Color color, int base_mipmap, int mipmap_count, int base_layer, int layer_count)Parameters
texture_copy(RID, RID, Vector3, Vector3, Vector3, int, int, int, int)
Copies the from_texture to to_texture with the specified from_pos, to_pos and size coordinates. The Z axis of the from_pos, to_pos and size must be 0 for 2-dimensional textures. Source and destination mipmaps/layers must also be specified, with these parameters being 0 for textures without mipmaps or single-layer textures. Returns @GlobalScope.OK if the texture copy was successful or @GlobalScope.ERR_INVALID_PARAMETER otherwise.
Note: from_texture texture can't be copied while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to RenderingDevice.FINAL_ACTION_CONTINUE) to copy this texture.
Note: from_texture texture requires the RenderingDevice.TEXTURE_USAGE_CAN_COPY_FROM_BIT to be retrieved.
Note: to_texture can't be copied while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to RenderingDevice.FINAL_ACTION_CONTINUE) to copy this texture.
Note: to_texture requires the RenderingDevice.TEXTURE_USAGE_CAN_COPY_TO_BIT to be retrieved.
Note: from_texture and to_texture must be of the same type (color or depth).
int 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)Parameters
from_textureRIDto_textureRIDfrom_posVector3to_posVector3sizeVector3src_mipmapintdst_mipmapintsrc_layerintdst_layerint
texture_create(RDTextureFormat, RDTextureView, PackedByteArray[])
Creates a new texture. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
Note: Not to be confused with RenderingServer.texture_2d_create, which creates the Godot-specific Texture2D resource as opposed to the graphics API's own texture type.
RID texture_create(RDTextureFormat format, RDTextureView view, PackedByteArray[] data)Parameters
formatRDTextureFormatviewRDTextureViewdataPackedByteArray[]
texture_create_from_extension(int, int, int, int, int, int, int, int, int)
Returns an RID for an existing image (VkImage) with the given type, format, samples, usage_flags, width, height, depth, and layers. This can be used to allow Godot to render onto foreign images.
RID texture_create_from_extension(int type, int format, int samples, int usage_flags, int image, int width, int height, int depth, int layers)Parameters
texture_create_shared(RDTextureView, RID)
Creates a shared texture using the specified view and the texture information from with_texture.
RID texture_create_shared(RDTextureView view, RID with_texture)Parameters
viewRDTextureViewwith_textureRID
texture_create_shared_from_slice(RDTextureView, RID, int, int, int, int)
Creates a shared texture using the specified view and the texture information from with_texture's layer and mipmap. The number of included mipmaps from the original texture can be controlled using the mipmaps parameter. Only relevant for textures with multiple layers, such as 3D textures, texture arrays and cubemaps. For single-layer textures, use RenderingDevice.texture_create_shared.
For 2D textures (which only have one layer), layer must be 0.
Note: Layer slicing is only supported for 2D texture arrays, not 3D textures or cubemaps.
RID texture_create_shared_from_slice(RDTextureView view, RID with_texture, int layer, int mipmap, int mipmaps, int slice_type)Parameters
texture_get_data(RID, int)
Returns the texture data for the specified layer as raw binary data. For 2D textures (which only have one layer), layer must be 0.
Note: texture can't be retrieved while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to RenderingDevice.FINAL_ACTION_CONTINUE) to retrieve this texture. Otherwise, an error is printed and a empty PackedByteArray is returned.
Note: texture requires the RenderingDevice.TEXTURE_USAGE_CAN_COPY_FROM_BIT to be retrieved. Otherwise, an error is printed and a empty PackedByteArray is returned.
Note: This method will block the GPU from working until the data is retrieved. Refer to RenderingDevice.texture_get_data_async for an alternative that returns the data in more performant way.
PackedByteArray texture_get_data(RID texture, int layer)Parameters
texture_get_data_async(RID, int, Callable)
Asynchronous version of RenderingDevice.texture_get_data. RenderingDevice will call callback in a certain amount of frames with the data the texture had at the time of the request.
Note: At the moment, the delay corresponds to the amount of frames specified by rendering/rendering_device/vsync/frame_queue_size.
Note: Downloading large textures can have a prohibitive cost for real-time even when using the asynchronous method due to hardware bandwidth limitations. When dealing with large resources, you can adjust settings such as rendering/rendering_device/staging_buffer/texture_download_region_size_px and rendering/rendering_device/staging_buffer/block_size_kb to improve the transfer speed at the cost of extra memory.
func _texture_get_data_callback(array):
value = array.decode_u32(0)
...
rd.texture_get_data_async(texture, 0, _texture_get_data_callback)
int texture_get_data_async(RID texture, int layer, Callable callback)Parameters
texture_get_format(RID)
Returns the data format used to create this texture.
RDTextureFormat texture_get_format(RID texture)Parameters
textureRID
texture_get_native_handle(RID)
Returns the internal graphics handle for this texture object. For use when communicating with third-party APIs mostly with GDExtension.
Note: This function returns a uint64_t which internally maps to a GLuint (OpenGL) or VkImage (Vulkan).
int texture_get_native_handle(RID texture)Parameters
textureRID
texture_is_discardable(RID)
Returns true if the texture is discardable, false otherwise. See RDTextureFormat or RenderingDevice.texture_set_discardable.
bool texture_is_discardable(RID texture)Parameters
textureRID
texture_is_format_supported_for_usage(int, int)
Qualifiers: const
Returns true if the specified format is supported for the given usage_flags, false otherwise.
bool texture_is_format_supported_for_usage(int format, int usage_flags)Parameters
texture_is_shared(RID)
Returns true if the texture is shared, false otherwise. See RDTextureView.
bool texture_is_shared(RID texture)Parameters
textureRID
texture_is_valid(RID)
Returns true if the texture is valid, false otherwise.
bool texture_is_valid(RID texture)Parameters
textureRID
texture_resolve_multisample(RID, RID)
Resolves the from_texture texture onto to_texture with multisample antialiasing enabled. This must be used when rendering a framebuffer for MSAA to work. Returns @GlobalScope.OK if successful, @GlobalScope.ERR_INVALID_PARAMETER otherwise.
Note: from_texture and to_texture textures must have the same dimension, format and type (color or depth).
Note: from_texture can't be copied while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to RenderingDevice.FINAL_ACTION_CONTINUE) to resolve this texture.
Note: from_texture requires the RenderingDevice.TEXTURE_USAGE_CAN_COPY_FROM_BIT to be retrieved.
Note: from_texture must be multisampled and must also be 2D (or a slice of a 3D/cubemap texture).
Note: to_texture can't be copied while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to RenderingDevice.FINAL_ACTION_CONTINUE) to resolve this texture.
Note: to_texture texture requires the RenderingDevice.TEXTURE_USAGE_CAN_COPY_TO_BIT to be retrieved.
Note: to_texture texture must not be multisampled and must also be 2D (or a slice of a 3D/cubemap texture).
int texture_resolve_multisample(RID from_texture, RID to_texture)Parameters
texture_set_discardable(RID, bool)
Updates the discardable property of texture.
If a texture is discardable, its contents do not need to be preserved between frames. This flag is only relevant when the texture is used as target in a draw list.
This information is used by RenderingDevice to figure out if a texture's contents can be discarded, eliminating unnecessary writes to memory and boosting performance.
void texture_set_discardable(RID texture, bool discardable)Parameters
texture_update(RID, int, PackedByteArray)
Updates texture data with new data, replacing the previous data in place. The updated texture data must have the same dimensions and format. For 2D textures (which only have one layer), layer must be 0. Returns @GlobalScope.OK if the update was successful, @GlobalScope.ERR_INVALID_PARAMETER otherwise.
Note: Updating textures is forbidden during creation of a draw or compute list.
Note: The existing texture can't be updated while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to RenderingDevice.FINAL_ACTION_CONTINUE) to update this texture.
Note: The existing texture requires the RenderingDevice.TEXTURE_USAGE_CAN_UPDATE_BIT to be updatable.
int texture_update(RID texture, int layer, PackedByteArray data)Parameters
textureRIDlayerintdataPackedByteArray
uniform_buffer_create(int, PackedByteArray, int)
Creates a new uniform buffer. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID uniform_buffer_create(int size_bytes, PackedByteArray data, int creation_bits)Parameters
size_bytesintdataPackedByteArraycreation_bitsint
uniform_set_create(RDUniform[], RID, int)
Creates a new uniform set. It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID uniform_set_create(RDUniform[] uniforms, RID shader, int shader_set)Parameters
uniform_set_is_valid(RID)
Checks if the uniform_set is valid, i.e. is owned.
bool uniform_set_is_valid(RID uniform_set)Parameters
uniform_setRID
vertex_array_create(int, int, RID[], PackedInt64Array)
Creates a vertex array based on the specified buffers. Optionally, offsets (in bytes) may be defined for each buffer.
RID vertex_array_create(int vertex_count, int vertex_format, RID[] src_buffers, PackedInt64Array offsets)Parameters
vertex_countintvertex_formatintsrc_buffersRID[]offsetsPackedInt64Array
vertex_buffer_create(int, PackedByteArray, int)
It can be accessed with the RID that is returned.
Once finished with your RID, you will want to free the RID using the RenderingDevice's RenderingDevice.free_rid method.
RID vertex_buffer_create(int size_bytes, PackedByteArray data, int creation_bits)Parameters
size_bytesintdataPackedByteArraycreation_bitsint
vertex_format_create(RDVertexAttribute[])
Creates a new vertex format with the specified vertex_descriptions. Returns a unique vertex format ID corresponding to the newly created vertex format.
int vertex_format_create(RDVertexAttribute[] vertex_descriptions)Parameters
vertex_descriptionsRDVertexAttribute[]