Release notes

Changelog #

Version 1.9.0.11 #

Version 1.9.0.12 #

Version 1.9.2.2 #

Version 1.9.2.4 #

Version 1.9.5.4 #

Version 1.9.7.2 #

Version 1.9.9.2 #

Version 1.9.9.5 #

Version 1.9.9.8 #

Migration guide #

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, destruction, 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 those kinds 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 until now, 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 STL-based containers and STL-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.

Example:

// Create an instance of a class that inherits IBackendAllocator
EngineBackendAllocator m_EngineBackendAllocator(...);
...
// Create a backend and initialize it with the desired custom IBackendAllocator
auto 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.

Transitioning to Prysm 1.9.5 #

New fields in the 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.