RenderPass

  • See samples/testDrv3d/render_pass_tests.h for example usage

Callable d3d:: methods

RenderPass *create_render_pass(const RenderPassDesc &rp_desc)

Creates render pass object.

Render pass objects are intended to be created once (and ahead of time), used many times

Note

No external sync required

Warning

Do not run per frame/realtime!

Warning

Avoid using at time sensitive places!

Warning

Will assert-fail if rp_desc.bindCount is 0

Parameters:

rp_desc – Description of render pass to be created

Returns:

Pointer to opaque RenderPass object, may be nullptr if description is invalid

void delete_render_pass(RenderPass *rp)

Deletes render pass object.

Note

Sync with usage is required (must not delete object that is in use in current CPU frame)

Warning

All usage to object becomes invalid right after method call

Parameters:

rp – Object to be deleted

void begin_render_pass(RenderPass *rp, const RenderPassArea area, const RenderPassTarget *targets)

Begins render pass rendering.

After this command, viewport is reset to area supplied and subpass 0, described in render pass object, is started

Note

Must be external synced (GPU lock required)

Warning

When inside pass, all other GPU execution methods aside of Draw* are prohibited!

Warning

Avoid writes/reads outside area, it is UB in general

Warning

Will assert-fail if other render pass is already in process

Warning

Backbuffer can’t be used as target

Parameters:

  • rp – Render pass resource to begin with

  • area – Rendering area restriction

  • targets – Array of targets that will be used in rendering

void next_subpass()

Advances to next subpass.

Increases subpass number and executes necessary synchronization as well as binding, described for this subpass

Viewport is reset to render area on every call

Note

Must be external synced (GPU lock required)

Warning

Will assert-fail if there is no subpass to advance to

Warning

Will assert-fail if called outside of render pass

void end_render_pass()

Ends render pass.

Processes store&sync operations described in render pass

After this call, any non Draw operations are allowed and render targets are reset to backbuffer

Note

Must be external synced (GPU lock required)

Warning

Will assert-fail if subpass is not final

Warning

Will assert-fail if called outside of render pass

inline void allow_render_pass_target_load()

When renderpass splits validation is enabled in Vulkan this command tells that we actually want to load previous contents of attached color targets or depth to render on top of it. Otherwise loading previous contents treated as renderpass split and the validation fails (we want to avoid RP splits cause of performance impact on TBDR). If it’s known that the render target will be just fully redrawn (like in most postfx), it’s better to use d3d::clearview(CLEAR_DISCARD, …) instead of this command.

Related structures

struct RenderPassBind

Description of render target bind inside render pass.

Fully defines operation that will happen with target at defined subpass slot

Public Members

int32_t target

Index of render target in render targets array that will be used for this bind.

int32_t subpass

Index of subpass where bind happens.

int32_t slot

Index of slot where target will be used.

RenderPassTargetAction action

defines what will happen with target used in binding

ResourceBarrier dependencyBarrier

optional user barrier for generic(emulated) implementation

struct RenderPassTargetDesc

Early description of render target.

Gives necessary info at render pass creation so render pass is compatible with targets of same type later on

Public Members

BaseTexture *templateResource

Resource from which information is extracted, can be nullptr.

unsigned texcf

Raw texture create flags, used if template resource is not provided.

bool aliased

Must be set if template resource is empty and target will use memory aliased inside render pass.

struct RenderPassTarget

Description of target that is used inside render pass.

Public Members

RenderTarget resource

Actual render target subresource reference.

ResourceClearValue clearValue

Clear value that is used on clear action.

struct RenderPassDesc

Render pass resource description, used to create RenderPass object.

Public Members

const char *debugName

Name that is visible only in developer builds and inside graphics tools, if possible.

uint32_t targetCount

Total amount of targets inside render pass.

uint32_t bindCount

Total amount of bindings for render pass.

const RenderPassTargetDesc *targetsDesc

Array of targetCount elements, supplying early description of render target.

const RenderPassBind *binds

Array of bindCount elements, describing all subpasses.

uint32_t subpassBindingOffset

Texture binding offset for shader subpass reads used on APIs without native render passes.

Generic(emulated) implementation will use registers starting from this offset, to bind input attachments. This must be properly handled inside shader code for generic implementation to work properly!

struct RenderPassArea

Area of render target where rendering will happen inside render pass.

Public Members

uint32_t left
uint32_t top
uint32_t width
uint32_t height
float minZ
float maxZ

Related constants

enum RenderPassTargetAction

Bitfield of actions that happen with target at given slot and subpass.

Values:

enumerator RP_TA_NONE

No action with target will happen.

Only dependencyBarrier of binding will be executed for this target

Warning

Content of target becomes invalid if no action is supplied overall

enumerator RP_TA_LOAD_READ

Loads contents of target from memory to framebuffer.

Note

Avoid load operations on TBDR hardware

enumerator RP_TA_LOAD_CLEAR

Loads clear value to framebuffer instead of doing any memory operation.

enumerator RP_TA_LOAD_NO_CARE

Don’t care about loading contents of target (aka discard)

Warning

Initial content of frame buffer is underfined, make sure to handle this

enumerator RP_TA_LOAD_MASK

Bitmask of any load operation.

Note

load action is performed for each target when its being accessed for the first time in render pass

enumerator RP_TA_SUBPASS_READ

Target contents will be readed by subpass.

Note

This corresponds to SubpassInput with SubpassLoad inside shader

Warning

Generic implementation uses T register with subpassBindingOffset instead of SubpassInput, this must be handled properly in shader code

enumerator RP_TA_SUBPASS_RESOLVE

Target will be used as MSAA resolve destination of MSAA target bound in same slot.

Note

MSAA Depth resolve is optional feature if non generic implementation is used

Warning

Must supply MSAA target in same slot in another binding otherwise creation on render pass will fail

enumerator RP_TA_SUBPASS_WRITE

Target contents will be written by subpass.

enumerator RP_TA_SUBPASS_KEEP

Target contents will be keeped intact if it was not used in subpass (otherwise UB)

enumerator RP_TA_SUBPASS_MASK

Bitmask of any subpass operation.

enumerator RP_TA_STORE_WRITE

Contents of framebuffer will be written to target memory.

enumerator RP_TA_STORE_NONE

Contents of framebuffer will not be stored.

enumerator RP_TA_STORE_NO_CARE

Don’t care about target memory contents.

Warning

Target memory contents will be left in UB state

enumerator RP_TA_STORE_MASK

Bitmask of any load operation.

Note

store action is performed once for each target on whole pass completion

enum RenderPassExtraIndexes

extra indexes that encode special cases of render pass description

Values:

enumerator RP_INDEX_NORMAL
enumerator RP_SUBPASS_EXTERNAL_END

Pseudo subpass index, that happens at end of render pass.

Used to provide store actions as well as dependencyBarriers for generic implementation

enumerator RP_SLOT_DEPTH_STENCIL

Slot for depth/stencil.

Using this slot will bind target as depth/stencil

inline constexpr RenderPassTargetAction operator|(RenderPassTargetAction l, RenderPassTargetAction r)