Resource update buffers

The file contains the API for so-called RUBs (Resource Update Buffers). These are used to update contents of resources efficiently on modern graphics APIs.

namespace d3d

Functions

ResUpdateBuffer *allocate_update_buffer_for_tex_region(BaseTexture *dest_base_texture, unsigned dest_mip, unsigned dest_slice, unsigned offset_x, unsigned offset_y, unsigned offset_z, unsigned width, unsigned height, unsigned depth)

Allocates a update buffer to update the subregion described by offset_x, offset_y, offset_z, width, height and depth.

  • dest_base_texture can not be nullptr.

  • dest_mip must be a valid mipmap level for dest_base_texture

  • dest_slice must be a valid array index / cube face for dest_base_texture when it is a array, cube or cube array texture, otherwise has to be 0

  • offset_x must be within the width of dest_base_texture of miplevel dest_mip and aligned to the texture format block size

  • offset_y must be within the height of dest_base_texture of miplevel dest_mip and aligned to the texture format block size

  • offset_z must be within the depth of dest_base_texture of miplevel dest_mip when the texture is a vol tex, otherwise has to be 0

  • width plus offset_x must be within the width of dest_base_texture of miplevel dest_mip and aligned to the texture format block size

  • height plus offset_y must be within the height of dest_base_texture of miplevel dest_mip and aligned to the texture format block size

  • depth plus offset_z must be within the depth of dest_base_texture of miplevel dest_mip when the texture is a vol tex, otherwise has to be 1

May return nullptr if either inputs violate the rules above, the driver can currently not provide the memory required or the driver is unable to perform the needed copy operation on update.

ResUpdateBuffer *allocate_update_buffer_for_tex(BaseTexture *dest_tex, int dest_mip, int dest_slice)

Allocates update buffer in system memory to be filled directly and then dispatched to apply_tex_update_buffer.

Warning

This method can fail if too much allocations happens in N-frame period. Caller should retry after rendering frame on screen if this happens.

Parameters:

  • dest_tex – destination texture

  • dest_mip – destination mip level

  • dest_slice – destination slice

Returns:

pointer to update buffer or nullptr if allocation failed

void release_update_buffer(ResUpdateBuffer *&rub)

Releases update buffer (clears pointer afterwards); skips any update, just releases data.

Parameters:

rub – update buffer to release

char *get_update_buffer_addr_for_write(ResUpdateBuffer *rub)

Returns data address to fill update data.

Parameters:

rub – update buffer

Returns:

pointer to memory that should be filled with data

size_t get_update_buffer_size(ResUpdateBuffer *rub)

Returns size of update buffer.

Parameters:

rub – update buffer

Returns:

size of update buffer in bytes

size_t get_update_buffer_pitch(ResUpdateBuffer *rub)

Returns pitch of update buffer (if applicable)

Parameters:

rub – update buffer

Returns:

pitch of update buffer

size_t get_update_buffer_slice_pitch(ResUpdateBuffer *rub)

Returns the pitch of one 2d image slice for volumetric textures.

Parameters:

rub – update buffer

Returns:

pitch of of a slice in the update buffer

bool update_texture_and_release_update_buffer(ResUpdateBuffer *&src_rub)

applies update to target d3dres and releases update buffer (clears pointer afterwards)

Parameters:

src_rub – update buffer to apply

Returns:

true if update was successful, false if update failed