NoesisGUI

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

© 2017 Noesis Technologies