RenderDevice API
The following sections describe the changes in the API of RenderDevice for each version of NoesisGUI. If you are implementing your own renderer these notes will help you to easily transition to new versions of NoesisGUI.
Many of the changes are straightforward and can be discovered by doing source code diffs between the current version and the new one. Our reference renderers include source code. For its simplicity we recommend using D3D11RenderDevice and MTLRenderDevice for this purpose.
NoesisGUI 3.1
- A new parameter, 'needsStencil', was added to CreateRenderTarget() to indicate if stencil must be created or not.
- BeginRender(bool offscreen) was removed and substituted by BeginOffscreenRender() and BeginOnscreenRender().
- EndRender() removed and substituted by EndOffscreenRender() and EndOnscreenRender().
- BeginTile() and EndTile() functions were removed. The main purpose of these functions was clearing a rectangle area of the render target with a transparent color (#000000). We have simplified and optimized this part by sending these rectangles with the rest of primitives using DrawBatch. There is a new shader for this purpose: Shader::Clear and a new stencil mode: StencilMode::Clear.
- Texture base class has a new virtual method: HasAlpha(). It must return true if the texture has an alpha channel that is not completely white. This is just a hint to optimize rendering as alpha blending can be disabled when this function returns false. A new texture format has also been added (TextureFormat::RGBX8) to indicate a 32 bits RGBA texture with unused alpha channel.
- New vertex attributes: Rect, Tile and ImagePos. The attribute Tex2 has been removed. The documentation for each attribute and shaders has been improved in RenderDevice.h.
Attr Format Bytes Interpolation Semantic Pos R32G32_FLOAT 8 linear Position (xy) Color R8G8B8A8_UNORM 4 nointerpolation Color (rgba) Tex0 R32G32_FLOAT 8 linear TexCoord0 (uv) Tex1 R32G32_FLOAT 8 linear TexCoord1 (uv) Coverage R32_FLOAT 4 linear Coverage (alpha) Rect R16G16B16A16_UNORM 8 nointerpolation Rect (x0, y0, x1, y1) Tile R32G32B32A32_FLOAT 16 nointerpolation Rect (x, y, width, height) ImagePos R32G32B32A32_FLOAT 16 linear Position (xy) - Scale(zw)
- Vertex attribute Color is now always passed in sRGB format (R8G8B8A8). If the device is working in linear mode (DeviceCaps.linearRendering is true) then the vertex shader is in charge of doing the conversion to linear space. See the function SRGBToLinear() in our reference shaders.
- The number of vertex shaders has been increased from 11 to 21. They use the same definitions as before.
Index Vertex Shader Vertex Format #00 Pos #00 #01 PosColor #01 #02 PosTex0 #02 #03 PosTex0Rect #03 #04 PosTex0RectTile #04 #05 PosColorCoverage #05 #06 PosTex0Coverage #06 #07 PosTex0CoverageRect #07 #08 PosTex0CoverageRectTile #08 #09 PosColorTex1_SDF #09 #10 PosTex0Tex1_SDF #10 #11 PosTex0Tex1Rect_SDF #11 #12 PosTex0Tex1RectTile_SDF #12 #13 PosColorTex1 #09 #14 PosTex0Tex1 #10 #15 PosTex0Tex1Rect #11 #16 PosTex0Tex1RectTile #12 #17 PosColorTex0Tex1 #13 #18 PosTex0Tex1_Downsample #10 #19 PosColorTex1Rect #14 #20 PosColorTex0RectImagePos #15
- New pixel shaders. Blur and Shadow are now single pass and use the result of a gaussian pass performed with Downsample and Upsample shaders. We also added Pattern_* variants that clamp in the pixel shader.
Pixel Shader Vertex Shader Notes RGBA #00 Shader for debug modes Mask #00 Stencil only with null pixel shader Clear #00 Shader used for clearing render target Path_Solid #01 Shaders for rendering geometry Path_Linear #02 Path_Radial #02 Path_Pattern #02 Path_Pattern_Clamp #03 Path_Pattern_Repeat #04 Path_Pattern_MirrorU #04 Path_Pattern_MirrorV #04 Path_Pattern_Mirror #04 Path_AA_Solid #05 Shaders for rendering geometry with PPAA Path_AA_Linear #06 Path_AA_Radial #06 Path_AA_Pattern #06 Path_AA_Pattern_Clamp #07 Path_AA_Pattern_Repeat #08 Path_AA_Pattern_MirrorU #08 Path_AA_Pattern_MirrorV #08 Path_AA_Pattern_Mirror #08 SDF_Solid #09 Shaders for rendering distance fields SDF_Linear #10 SDF_Radial #10 SDF_Pattern #10 SDF_Pattern_Clamp #11 SDF_Pattern_Repeat #12 SDF_Pattern_MirrorU #12 SDF_Pattern_MirrorV #12 SDF_Pattern_Mirror #12 SDF_LCD_Solid #09 Shaders for rendering distance fields with subpixel rendering.
SDF_LCD_* shaders are only used when the device reports support for subpixel rendering in DeviceCaps. Otherwise SDF_* shaders are used
SDF_LCD_Linear #10 SDF_LCD_Radial #10 SDF_LCD_Pattern #10 SDF_LCD_Pattern_Clamp #11 SDF_LCD_Pattern_Repeat #12 SDF_LCD_Pattern_MirrorU #12 SDF_LCD_Pattern_MirrorV #12 SDF_LCD_Pattern_Mirror #12 Opacity_Solid #13 Shaders for offscreen rendering Opacity_Linear #14 Opacity_Radial #14 Opacity_Pattern #14 Opacity_Pattern_Clamp #15 Opacity_Pattern_Repeat #16 Opacity_Pattern_MirrorU #16 Opacity_Pattern_MirrorV #16 Opacity_Pattern_Mirror #16 Upsample #17 Gaussian upsampling step Downsample #18 Gaussian downsampling step Shadow #19 Shadow rendering Blur #13 Blur rendering Custom_Effect #20 Custom pixel shader
- New enumerations added. Renderer implementations should use them to be more compatible with future changes:
- Noesis::Shader::Vertex
- Noesis::Shader::Vertex::Format
- Noesis::Shader::Vertex::Format::Attr
- Noesis::Shader::Vertex::Format::Attr::Type
- New tables are exposed: VertexForShader[], FormatForVertex[], SizeForFormat[], AttributesForFormat[], TypeForAttr[], SizeForType[]. They simplify the implementation of new renderers and make them more robust to future changes.
- Support for custom shaders was added. Batch now has an extra member for that purpose: void* pixelShader.
- Constant buffers are now specified in the Batch structure with data and hashes for each binding. This simplifies the implementation on each renderer.
// Uniform shader values. For unused buffers, 'values' is set to null and 'numDwords' is zero. // A hash for the content is given to avoid unnecessary constant buffer updates struct UniformData { const void* values; uint32_t numDwords; uint32_t hash; };
- New blending modes:
Blend Mode Src Dest SrcAlpha DestAlpha SrcOver_Multiply DEST_COLOR INV_SRC_ALPHA BLEND_ONE INV_SRC_ALPHA SrcOver_Screen BLEND_ONE INV_SRC_COLOR BLEND_ONE INV_SRC_ALPHA SrcOver_Additive BLEND_ONE BLEND_ONE BLEND_ONE INV_SRC_ALPHA
- New stencil mode:
Stencil Mode Stencil Func Stencil Pass Clear FUNC_ALWAYS OP_ZERO
- Scissoring is no longer part of the render state and must be always disabled.
- Our renderer implementations are now using a texture lod bias of -0.75, this helps with the blurriness when using mipmaps (in 3.1 our app framework is generating mipmaps for all textures)
Table of Contents