Transitioning from Prysm 1.1 to 1.2

This section outlines the changes you need to apply in order to upgrade from Prysm versions 1.1 and prior to 1.2 and later.

The current backend API was designed around DirectX 11 and therefore implementing a DirectX 11 backend with the current API is simple and intuitive. However, with the advent of modern low-level APIs (e.g. Dx12, Metal and Vulkan) and concepts such as render passes, enhancements of the backend API were needed, so that the backend implementation for those graphics APIs is easier and more efficient.

You can read more about the motivation for the backend API changes here.

In Prysm 1.2, Renoir's backend API has been modified significantly with the introduction of 2 new commands, 4 new Renoir Core capabilities and one new shader type. There are also several changes in the graphics backend that must be adapted from previous versions in order for the new version to work.

If you prefer to make minimal changes to you backend and not use the new capabilities, here are the steps for migrating:

Add the following lines to the FillCaps method

outCaps.ShouldUseRenderPasses = false;
outCaps.ShouldClearRTWithClearQuad = false;
outCaps.ConstantBufferBlocksCount = 1;
outCaps.ConstantBufferRingSize = 1;
...
outCaps.ShaderMapping[ST_ClearQuad] = ST_ClearQuad;

Add unsigned size as last argument of the CreateConstantBuffer method and use it for the constant buffer allocation size. This is how the CreateConstantBuffer method declaration in the backend header should look like:

virtual bool CreateConstantBuffer(CBType type, ConstantBufferObject object, unsigned size) override;

Example of using the size parameter on constant buffer creation from the DirectX11 backend:

bool Dx11Backend::CreateConstantBuffer(CBType, ConstantBufferObject object, unsigned size)
{
    D3D11_BUFFER_DESC bufferDesc;
    bufferDesc.ByteWidth = size;
    ...
    // Create the constant buffer with the filled buffer description
    m_Device->CreateBuffer(&bufferDesc, ..)
}

In SetRenderTarget stop using EnableColorWrites flag as it is no longer present and instead handle the PipelineState's ColorMask field in CreatePipelineState. This field currently only supports the values ColorWriteMask:CWM_None and ColorWriteMask::CWM_All, which correspond to the previous false and true values of EnableColorWrites. Set the appropriate value of the graphics API's render target color write mask. E.g. in DirectX11 the write mask is placed in the description of the blend state:
```
bool Dx11Backend::CreatePipelineState(const PipelineState& state, PipelineStateObject object)
{
    ...
    D3D11_BLEND_DESC desc;
    desc.RenderTarget[0].RenderTargetWriteMask = UINT8(state.ColorMask);
    ...
    // Create the blend state with the filled description
    m_Device->CreateBlendState(&desc, ...)
}
```
In ExecuteRendering add empty cases with only break in them for BC_BeginRenderPass and BC_EndRenderPass:
```
case BC_BeginRenderPass:
{
    break;
}
break;
case BC_EndRenderPass:
{
    break;
}
break;
```

The MSAASamples field was added to the PipelineState structure, so you may start using it in CreatePipelineState.

Below we will describe each new capability, how it can affect you backend and what are the needed changes you need to make to use it.

When the ShouldUseRenderPasses capability is enabled, then Renoir starts enqueuing the commands BeginRenderPass and EndRenderPass and stops issuing the SetRenderTarget and ResolveRenderTarget commands. The BeginRenderPass command provides all the needed information for starting a render pass in modern graphics APIs like Metal and Vulkan. This information includes the render targets, whether they should be cleared on render pass load and if they should be resolved on store. Here are the additional steps you need to make to start using this capability:

Set ShouldUseRenderPasses to true in the FillCaps method
You can remove the implementation of the SetRenderTarget and ResolveRenderTarget methods and add an assert that they are never called
Implement a BeginRenderPass method, which handles the corresponding command by using the provided information by it to begin a render pass in the graphics API
Implement a EndRenderPass method, which handles the corresponding command by ending the current render pass and possibly also resetting any currently kept state of the render pass. E.g. in our Metal backend the implementation of the EndRenderPass method is the following:
```
[m_State->CurrentCmdEncoder endEncoding];
m_State->CurrentCmdEncoder = nil;
m_State->BoundGPUState = GPUState();
```

Enabling the ShouldClearRTWithClearQuad capability will make Renoir issue fullscreen clear quad instead of calling ClearRenderTarget. The clear quad is done through a new vertex and pixel shader. The capability was added so that we don't need to create a new render pass to clear a render target in graphics APIs like Metal, which do not provide an easier way to do it. Here are the additional steps you need to make to start using this capability:

Set ShouldClearRTWithClearQuad to true in the FillCaps method
You can remove the implementation of the ClearRenderTarget method and add an assert that it is never called
You need to create a new ST_ClearQuad vertex and pixel shader, compile them if necessary and start using them. You can check out the example ST_ClearQuad HLSL shaders provided with the DirectX11 backend. The Metal backend is using the clear quad capability, so you can check out how to use the new shaders in its implementation.

The ConstantBufferRingSize capability allows you to set the size of the internal ring buffer, which is used to manage Renoir's constant buffers. We recommend to set this size to 4 for low-level graphics APIs like Dx12, Metal and Vulkan. The motivation for this particular size is that the maximum count of buffered frames in a standard pipeline is three and in order to surely avoid overlap of constant buffers, they should be managed by a circular buffer with size 4. If you have a pipeline with higher maximum count of buffered frames, then this value should be changed accordingly. For most high-level graphics APIs ring buffer size should be set to 1, because the drivers for them handle constant buffer overlap internally and therefore a greater value for the ring buffer size is unnecessary.

The only steps you need to make to start using this capability are:

Set ConstantBufferRingSize to the appropriate value in the FillCaps method
If you have a ring buffer for the constant buffers in your backend, then you can remove it, because Renoir will do it automatically for you

The ConstantBufferBlocksCount capability allow you to set the count of aligned constant buffer blocks for each constant buffer type. Renoir will issue a CreateConstantBuffer call with size equal to (constant buffer blocks count) * (aligned specific constant buffer size) for each constant buffer type. If the blocks count value is greater than 1, then if the regular constant buffer becomes full, Renoir will make sure that a new auxiliary constant buffer is allocated. If the blocks count value is equal to 1, then Renoir won't create any auxiliary constant buffers. Auxiliary constant buffers are allocated per frame, thus being allocated before ExecuteRendering is called and deallocated immediately after that. Setting constant buffer ring size and blocks count value to greater than 1 usually goes hand in hand, because both provide functionality that otherwise should be explicitly implemented in the backend for low-level graphics APIs like Dx12, Metal and Vulkan. For other APIs that don't support constant buffers, but use uniform slots (e.g OpenGL) both capabilities should be set to 1 in order to avoid unnecessary constant buffer creation.

The only steps you need to make to start using this capability are:

Set ConstantBufferBlocksCount to the appropriate value in the FillCaps method
Remove all the logic in your backend, which manually creates auxiliary buffers once the regular ones are full. Renoir will create and manage them automatically

Transitioning from Prysm 1.7 to 1.8

Prysm version 1.8 introduces support for using images that do not have their alpha channel premultiplied into the other color channels. Prior to version 1.8, all images in the SDK were treated as if they were using premultiplied alpha, disregarding any image metadata that might tell otherwise.

User images (images that are preloaded by the engine, instead of decoded internally by Prysm) can now specify whether their alpha channel is premultiplied via the new cohtml::IAsyncResourceResponse::UserImageData::AlphaPremultiplication property. You can set the property to the correct value in the UserImageData object that is passed to the cohtml::IAsyncResourceResponse::ReceiveUserImage API in the cohtml::IAsyncResourceHandler::OnResourceRequest callback of your resource handler. This allows you to re-use the same image in both your engine and UI even if the engine uses a non-premultiplied alpha pipeline.

Following is a table that describes the differences and solutions for various image formats:

Format	1.7 and prior	1.8
PNG, JPG, Other RGB(A) formats	Automatically premultiplied after decode	No change - Automatically premultiplied after decode
DDS	Assumed to have premultiplied alpha	May need to re-save - Attempts to determine if alpha is premultiplied from metadata
KTX, ASTC, PKM	Assumed to have premultiplied alpha	Must re-save - Assumed NOT to have premultiplied alpha
User images	Assumed to have premultiplied alpha	User controlled via `cohtml::IAsyncResourceResponse::UserImageData::AlphaPremultiplication`

Note that the output of all operations in the Prysm is still an alpha-premultiplied texture so blending of the resulting UI texture is not affected.

Transitioning from Prysm 1.8 to 1.9

Prysm version 1.9 introduces two new features in all example backends - user texture and user depth stencil lifetime event callbacks and custom allocators.

User resources callbacks

User texture and depth stencil callbacks give the user the ability to be informed about user texture wrapping and destruction and user depth stencil wrapping and destruction. To enable this functionality the user is required to provide a class that inherits from IUserResourcesListener by calling the SetUserResourcesListener of the used backend. The backend will then inform the user about relevant events as they happen. If no such IUserResourcesListener is set, all backends will continue to work as they currently do. It's proper to point out that destruction callbacks will only be called for resources that have been wrapped after providing an IUserResourcesListener.

Example:

// Create an instance of a class that inherits IUserResourcesListener
EngineResourceListener m_EngineResourceListener(...);
...
// Create a backend and initialize it
auto dx11 = new renoir::Dx11Backend(...);
if (!dx11->InitializeStaticResources())
{
    APP_LOG(Error, "Unable to initialize backend static resources!");
    return false;
}
...
// Set the texture listener
dx11->SetUserResourcesListener(&m_EngineResourceListener);
...
// Wrap a user resource - texture/depth stencil
dx11->WrapUserTexture(userObject, description, object);
...
// Destroy a user resource - texture/depth stencil
dx11->DestroyTexture(object);
...
// Receive a callback in the EngineResourceListener::OnUserTextureDestroyed() callback
void EngineResourceListener::OnUserTextureDestroyed(void* userObject)
{
    // Inform the engine that the texture is no longer being used
}

Custom backend allocators

The second and bigger feature is the addition of user backend allocators that are used to allocate memory for data in the backends. Please note that this memory is only used by the backend itself, but it does not encompass memory needed by graphics driver calls (e.g. D3D). While for some backends this memory is required from the user anyway (e.g. PS4), in general the feature doesn't target that kind of allocations. To provide an allocator to the backend, the user might supply an object that implements the IBackendAllocator interface to the backend constructor. Once set, the allocator should NOT be changed and should be used for the whole lifetime of the backend. If no such allocator is set, everything will continue to work as it has to this moment, as there's a default malloc/free-based allocator provided.

Due to the specifics of each backend, there are some differences in the way and cases where these allocators are used.

For all backends the allocator is used for dynamically allocated objects and all std-based containers and std-based objects.
For the NVN backend - the allocator is also used for gpu allocations under the hood.
For the Vulkan backend - if no VulkanBackendAllocator is provided in its constructor, the default VulkanBackendAllocator implementation uses the IBackendAllocator passed to the VulkanBackend(if one is given) for allocations made inside it.
For the PS4 backend - the memory allocators that were passed in the constructor had their types changed to IBackendAllocator and are now used for everything that they were previously used for with the following improvement - the onion allocator now additionally handles the dynamic allocations inside the backend. Requires user changes.
For the PS5 backend - the memory allocator that was passed in the constructor had its type changed to IBackendAllocator and is now used for everything that it was used so far plus all dynamic allocations inside the backend. Requires user changes.