Renderer initialization on the Scaleform side involves the creation of Render::HAL. Render::HAL is a “hardware abstraction layer” interface that provides the Display method used to render movie objects; its specific implementations are located in platform-specific namespaces such as Render::D3D9::HAL and Render::PS4::HAL. Both of these are created and initialized with logic similar to the following:
D3DPRESENT_PARAMETERS PresentParams; IDirect3DDevice9* pDevice = ...; ThreadIdrenderThreadId = Scaleform::GetCurrentThreadId(); Render::ThreadCommandQueue *commandQueue = ...; Ptr<Render::D3D9::HAL> pHal; pHal = *SF_NEW Render::D3D9::HAL(commandQueue); if (!pHal->InitHAL(Render::D3D9::HALInitParams(pDevice, PresentParams, 0, renderThreadId))) { return false; }
The HALInitParams allows users to customize the behavior of some rendering systems, as well as communicate platform specific details about the rendering environment to the Scaleform renderer. In this example, HALInitParams uses pDevice and PresentParams to describe a D3D9 user-configured device. The exact parameters required per-platform can be found in the reference documentation for the platform’s HALInitParams structure.
The ‘renderThreadId’ parameter identifies the rendering thread used. ThreadCommandQueue is an interface instance that must be implemented for Scaleform to determine when rendering commands should be executed in relation to other user rendering commands. This interface is discussed in detail later in this document. HAL classes are not thread-safe and are designed to be used on the render thread only. They will usually be created on the render thread due to an initialization request or on the main thread while the render-thread is blocked.
In addition to the platform-specific rendering and threading details, the HALInitParams allows the user to override the platform’s TextureManager, RenderBufferManager and MemoryManager. These systems are responsible for allocating textures, render targets and graphics resource memory, respectively. A user-instantiated MemoryManager is required on PS4 to ensure that Scaleform allocations do not conflict with other user allocations. In all other cases reasonable default systems will be used if they are not provided.
In addition to customizable systems, the ‘halConfigParams’ parameter of the HALInitParam constructor provides the ability for the user to select certain features of the renderer. These are generally platform-specific, and are detailed in the table below.
Flag | Description |
---|---|
Render::HALConfig_SoftwareDeferredContext | Scaleform 4.4 and higher, D3D9 + GL only: enables the internal recording of rendering commands, to be executed on the render thread when calling HAL::Submit. |
D3D9::HALConfig_NoSceneCalls | IDirect3DDevice9::BeginScene and IDirect3DDevice9::EndScene will not be called internally by Scaleform. They must be called externally by the user. |
D3D9::HALConfig_StaticBuffers | Scaleform uses dynamic mesh buffers by default. Enabling this option will cause it to use static buffers, which may have performance implications. |
D3D9::HALConfig_ShaderModel20 | Scaleform uses Shader Model 3.0 shaders by default in D3D9. This flag forces the use of Shader Model 2.0 shaders. Note that this will disable certain filter shaders. |
GL::HALConfig_DynamicShaderCompile | By default all shaders are compiled on InitHAL. With this flag, shaders are only compiled when they are required. This can improve startup time and reduce memory usage. Note: all available binary shaders will still be loaded even when using this flag. |
GL::HALConfig_DisableBinaryShaders | Disables the use of binary shaders, even if the system supports them. |
GL::HALConfig_MultipleShaderCacheFiles | If binary shaders are used, they are saved in multiple files (one per shader). This is generally used with the HALConfig_DynamicShaderCompile flag, so that the entire shader cache file does not have to be rewritten after compiling each shader. |
GL::HALConfig_DisableShaderPipelines | Disables the use of separate shader pipelines, even if the system supports it. Separate shader pipelines can save significant shader memory. Note that if using binary shaders, this is automatically disabled. |
GL::HALConfig_DisableMultipassShaderCompile | By default, Scaleform will issue all shader compile commands, followed by program linking, and then validate the results. Using this flag performs each stage one shader at a time. Not applicable if using GL::HALConfig_DynamicShaderCompile. |
GL::HALConfig_DebugMessages | Enables the use of glDebugMessageCallbacks, if supported by the system. The messages are printed to the debug output. |
GL::HALConfig_NoVAO | Disables the use of Vertex Array Objects, even if they are supported by the system. |
GL::HALConfig_TraceGLExecution | Prints all GL commands and their parameters to the debug output on GL extension parsing. |