1.17.0.1
Prysm
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:
FillCaps method outCaps.ShouldUseRenderPasses = false;outCaps.ShouldClearRTWithClearQuad = false;outCaps.ConstantBufferBlocksCount = 1;outCaps.ConstantBufferRingSize = 1;...outCaps.ShaderMapping[ST_ClearQuad] = ST_ClearQuad;
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: Example of using the size parameter on constant buffer creation from the DirectX11 backend:virtual bool CreateConstantBuffer(CBType type, ConstantBufferObject object, unsigned size) override;
bool Dx11Backend::CreateConstantBuffer(CBType, ConstantBufferObject object, unsigned size){D3D11_BUFFER_DESC bufferDesc;bufferDesc.ByteWidth = size;...// Create the constant buffer with the filled buffer descriptionm_Device->CreateBuffer(&bufferDesc, ..)}
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 descriptionm_Device->CreateBlendState(&desc, ...)}
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:
ShouldUseRenderPasses to true in the FillCaps methodSetRenderTarget and ResolveRenderTarget methods and add an assert that they are never calledBeginRenderPass method, which handles the corresponding command by using the provided information by it to begin a render pass in the graphics APIEndRenderPass 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:
ShouldClearRTWithClearQuad to true in the FillCaps methodClearRenderTarget method and add an assert that it is never calledST_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:
ConstantBufferRingSize to the appropriate value in the FillCaps methodThe 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:
ConstantBufferBlocksCount to the appropriate value in the FillCaps methodPrysm 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.
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 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 IUserResourcesListenerEngineResourceListener m_EngineResourceListener(...);...// Create a backend and initialize itauto dx11 = new renoir::Dx11Backend(...);if (!dx11->InitializeStaticResources()){APP_LOG(Error, "Unable to initialize backend static resources!");return false;}...// Set the texture listenerdx11->SetUserResourcesListener(&m_EngineResourceListener);...// Wrap a user resource - texture/depth stencildx11->WrapUserTexture(userObject, description, object);...// Destroy a user resource - texture/depth stencildx11->DestroyTexture(object);...// Receive a callback in the EngineResourceListener::OnUserTextureDestroyed() callbackvoid EngineResourceListener::OnUserTextureDestroyed(void* userObject){// Inform the engine that the texture is no longer being used}
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.
VulkanBackendAllocator implementation uses the IBackendAllocator passed to the VulkanBackend(if one is given) for allocations made inside it.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.IBackendAllocator and is now used for everything that it was used so far plus all dynamic allocations inside the backend. Requires user changes.Example:
// Create an instance of a class that inherits IBackendAllocatorEngineBackendAllocator m_EngineBackendAllocator(...);...// Create a backend and initialize it with the desired custom IBackendAllocatorauto dx11 = new renoir::Dx11Backend(m_Renderer.get())->GetDevice(), false, m_PreferCPUWorkload, &m_EngineBackendAllocator);// All backend allocations will now use the m_EngineBackendAllocator// Again note that depending on the backend used, graphics driver calls may or may not// use the custom allocator for allocation.
renoir::RendererCaps structure.There are 2 new fields in the renoir::RendererCaps structure: renoir::RendererCaps::MaxTextureWidth and renoir::RendererCaps::MaxTextureHeight. The default versions of all backends are updated to fill in these values, which represent the maximum possible width and height of a 2D texture for the device, respectively. These values are used to limit the size of temporary textures that the Renoir library creates. A good default is 8192 by 8192 pixels, which is what was used internally before exposing these options.
renoir::RendererCaps::MaxTextureWidth and renoir::RendererCaps::MaxTextureHeight fields is required, since otherwise these limits will end up with uninitialized values and lead to undefined behavior.RendererCaps structure - CanOutputDepthInPixelShader and SupportsTwoSidedStencilOperations. Both must be supported by a given backend in order for the SDF-on-GPU to work. In case of at least one of them not being true, the fallback to the old algorithm is used. **Need to be set by user backends.ST_GenerateSDFOutline, ST_GenerateSDFSolid, ST_RenderSDF and ST_ClearQuadWithDepth) and shader mappings in the backends capabilities corresponding to the mentioned new shader types. Usually the pattern is as follows, but it's still subject to change. The mapping is done in the void FillCaps(RendererCaps& outCaps) method. Need to be set by user backends. Might be dummy values if the new feature is not used. outCaps.ShaderMapping[ST_GenerateSDFOutline] = ST_GenerateSDFOutline;outCaps.ShaderMapping[ST_GenerateSDFSolid] = ST_StandardRare;outCaps.ShaderMapping[ST_RenderSDF] = ST_Standard;outCaps.ShaderMapping[ST_ClearQuadWithDepth] = ST_ClearQuadWithDepth;
PixelShaderTypes that must be implemented in user shaders in order for the feature to work. These values are also subject to change. Need to be implemented by the user shaders in order for the feature to work. May be skipped otherwise. PST_SDFGenerateOutline = 20, // Generates the outline part of the glyphPST_SDFGenerateSolid = 21, // Generates the solid part of the glyphPST_SDFRender = 22, // Renders glyphs when drawing textPST_SDFOutlineRender = 23, // Renders glyphs with outline when drawing text
ClearQuadWithDepth pixel shader and the GenerateSDF pixel shader. Need to be implemented by the user backend in order for the feature to work. May be skipped otherwise.ClearQuadWithDepth one is only needed in backends that support the ShouldClearRTWithClearQuad capability and does the work of the ClearQuad pixel shader with the additional depth clearing to a given value. Backends that clear render targets with the ClearQuad shader, but can't implement this one can't use the new feature.GenerateSDF one is needed in backends that support the canOutputDepthInPixelShader and it generates glyph outlines(the first step in the glyph generation process). Backends that can't implement it due to some reason, can't use the new featureStencilFunc type to ComparisonFunction type along with its values and all references to them in order for this variable to better reflect its new usage(depth functions, stencil functions and so on). This affects the PipelineState objects. Users might need to check compatibility in their backends.BeginRenderPassCmd backend command to reflect those changes - added ShouldClearDepth, ClearDepthValue and RTFormat. Users might need to check compatibility in their backends.So far we only had support for offline user-generated Bitmap fonts. In this version we are introducing offline user-generated MSDF font support.
ST_RenderSDF shader type was removed and new ST_TextSDFGPU, ST_TextStrokeSDFGPU, ST_BatchedTextSDFGPU, ST_TextMSDF, ST_TextStrokeMSDF and ST_BatchedTextMSDF shader types were introduced and added to the shader mappings. The first three are used for rendering of SDF fonts generated on the GPU, while the other three are used for the newly introduced MSDF rendering. Client attention/changes required!PST_SDFRender and PST_SDDOutlineRender pixel shader source was moved from the CohShadeGeometry.ihlsl file to the CohShadeGeometryRare.ihlsl one. Client attention/changes required!PST_MSDFRender and PST_MSDFOutlineRender pixel shader types were implemented in the CohShadeGeometryRare.ihlsl file. Client attention/changes required!With the introduction of another type of user font, we decided to simplify the API for loading of user fonts.
cohtml::System::BitmapFontDescription object, but the new cohtml::System::UserFontDescription one. Aside from the changed name it has two new parameters. First is type of the font, which specifies whether we are using the old Bitmap font logic or the newly introduced MSDF one. The second one is spread which should be set to 0 in case of Bitmap fonts and to the correct value for fonts that are using distance fields like the MSDF fonts, for example.cohtml::System::AddBitmapFont functions have been changed to a pair of cohtml::System::AddUserFont ones that take the new cohtml::System::UserFontDescription configuration object instead of the old cohtml::System::BitmapFontDescription one. This means that all references to that type(and its subtypes) should be changed to reflect how the new API works.ST_ClearQuadWithDepth shader type which was writing depth in the pixel shader. Now we'll use the geometry to set Z values in the depth buffer and we'll use ST_ClearQuad shader type.
--allowSDFonGPU now becomes --disableSDFonGPU. With that, to restore the old behavior of the rendering library (SDF glyphs rendered on the CPU), the option --disableSDFonGPU has to be used.--sdfTextSizeThreshold. The old behavior of the rendering library can be restored when the option is used like --sdfTextSizeThreshold 18. To note is that this change also affects the font hinting for font sizes between 10 and 18. As a consequence, the effective width of some letters can change. The images below show the text rendering with the old and new default values.
--8bitGPUSDFTextures. To note is that if the 8 bit textures are in use, the provided shaders have to be recompiled with the define USE_8BIT_GPUSDF_ATLASES 1.renoir::PF_R16. The format is meant to represent 16 bit unsigned normalized values. That is, the create textures with this format are R16Unorm. In the backends, the 16 bit textures are created with this format. The one exception to this is the GLES2 backend where only 8 bit textures are created regardless of the renoir::PF_R16 format.Important The PS4 and PS5 backends create R16Float textures for the renoir::PF_R16 format because of a known blending issue with R16Unorm textures on these platforms.
renoir::PF_A8 is removed in favor of renoir::PF_R8. With that, all of the shaders and the backends are adjusted.ST_TextSDFGPU shader type is moved to the standard pixel shader – CohStandardPS.hlsl. The mappings in the backends are adjusted as well.ST_TextSDFGPU shader type. The code for drawing glyphs from GPU generated SDF atlas is in CohShadeGeometry.ihlsl. If the define COH_ALLOW_SS is present in the file during shader compilation, the multi-sampling is enabled. By default it is disabled. The multi-sampling does 4 takes samples of the glyph atlas to increases the quality of the rendered text at small font sizes – 14 and lower – but it also has a negative performance impact.As there are quite a few changes to the rendering pipeline, we'll summarize in several steps what is to be done in client code
ST_ClearQuadWithDepth shader type as it does not exist anymore.ST_TextSDFGPU shader type is not handled in the standard shader so the backend mappings have to be adjustedrenoir::PF_A8 is now renoir::PF_R8 so the backends and shaders have to be adjusted to handle it.renoir::PF_R16 is introduced so the backends should be able to create R16Unorm textures for it.