Aardvark 5.1 changelog

Aardvark 5.1 introduces a fair amount of changes and features, especially in Aardark.Rendering where a few aspects about the code base and the API have been reworked and cleaned up. This document is intended as a reference to make the process of porting from 5.0 to 5.1 easier for developers.

Base 5.1

• Matrix constructors with a single scalar value (e.g. M44d(2.0)) now only set the diagonal elements to that value (i.e. equivalent to M**.FromDiagonal).
• Reworked and extended color types to be more consistent and usable, added more descriptive comments (e.g. indicating whether range mapping is performed by a constructor).
• Color operations like multiplications no longer allow mixing of float and double operands. E.g. C4d * float32 is not supported anymore.
• Added vectors constructors from colors (e.g. V3f(C4f))
• Removed some obsolete code
• Added missing color conversion functions in static class Col
• Added statically resolved, generic conversion functions for matrix, vector and color types.
• Removed dynamic conversion functions in ColorConv. Use statically resolved generic functions named after the types instead (e.g. c4b : ^a -> C4b)
• Added overloads for Fun.Min and Fun.Max that work with a variable number of arguments.
• Added Vec.MinElement, Vec.MaxElement,Mat.MinElement, Mat.MaxElement
• Added Fun.AngleDistance and Fun.AngleDifference.
• Added ConstantF static class containing float32 constants. Consequently the following become obsolete:
  • Constant.PiF
  • ConstantSqrt2HalfF
  • ConstantLn2F
  • ConstantLn2InvF
  • ConstantOneThirdF
• Changed how Hull3d is constructed from a Box3d. Previously the (obsolete) constructor produced planes with normals pointing inside, while a correct implemention was found in Hull3d.Create. This situation is cleaned up now:
  • Fixed obsolete and incorrect Hull3d(Box3d) constructor by replacing with correct implementation in Hull3d.Create(Box3d)
  • Removed Hull3d.Create()
• Vec.Distance1 now returns the field type instead of double for integer vectors.
• Added Rot.SlerpShortest and Quaternion.SlerpShortest, making Ipol.SlerpShortest obsolete.
• Ipol<T> -> Ipol<T, U>
• Improved performance of indexers of the following types. They no longer throw IndexOutOfRangeException, but will fail silently with horrible consequences:
  • Vector types
  • Matrix types
  • Quaternion types
  • Rot types
  • Scale types
  • Shift types
  • Color types
• Added Capacity property to Dict*
• Improved Dict* enumerators
• Reduced telemetry probes overhead: avoiding allocations of disposable
• Restored Matrix<T> sampling performance: revered interpolation functions
• Improved M**.GetHashCode() performance
• Improved HashCode.Combine: eplicit overloads for up to 8 arguments avoids temporary array allocation
• Introspection and plugin cache files are named based on assembly version or file modification time (see https://github.com/aardvark-platform/aardvark.base/issues/49)
• Cleanup of Ray3d.Hits* intersections:
  • light-weight overloads only calculating 'out double t'
  • interesctions with untyped primitives (e.g. HitsSphere(center, radius, ..))
  • changed default t-range from [double.MinValue, double.MaxVaule] to [0, double.MaxValue]

Rendering 5.1

A good portion of the changes introduced by this major version comes from cleaning, reworking, and extending core aspects of Aardvark.Base.Rendering. First and foremost, the backend-independent base assembly has been renamed from Aardvark.Base.Rendering to Aardvark.Rendering to make it more consistent with the naming scheme of the other assemblies. Previously, this base library contributed to multiple namespaces, namely:

• Aardvark.Base
• Aardvark.Base.Rendering
• Aardvark.Rendering

This was confusing as finding the origin of a type that lived in the namespace Aardvark.Base, could be in the Aardvark.Base or Aardvark.Base.Rendering assemblies. Therefore, the rendering base assembly only populates the Aardvark.Rendering namespace from now on. Also, the Aardvark.GPGPU and Aardvark.Scenegraph assemblies contribute to their own namespaces. As a first step of porting to v5.1 apply the following rules:

1. Replace open Aardvark.Base.Rendering -> open Aardvark.Rendering
2. Add open Aardvark.Rendering in files that produce errors.
3. Add open Aardvark.Scenegraph in files that produce errors.
4. Add open Aardvark.GPGPU in files that produce errors related to GPGPU logic.

Powershell script to recursively update paket.references files:

$configFiles = Get-ChildItem . paket.references -rec
foreach ($file in $configFiles)
{
    (Get-Content $file.PSPath) |
    Foreach-Object { $_ -replace "Aardvark.Base.Rendering", "Aardvark.Rendering" } |
    Set-Content $file.PSPath
}

Pipeline states rework

The way pipeline states were represented and handled, was changed in this release, making it more consistent and extending it with missing functionality required for some more advanced rendering techniques. First of all, a number of types have been renamed:

• Renamed DepthBiasState to DepthBias
• Renamed SamplerStateDescription to SamplerState
• Renamed StencilState to StencilMode
• Renamed DepthTestMode to DepthTest

Those types and BlendMode have been evacuated from the Aardvark.Base.Rendering namespace in Aardvark.Base and are now records making their construction in F# easier. Moreover, modules named after the types were added, which contain construction utilities. For stencil modes in particular, however, it is recommended to use the explicit record construction syntax. That way it is immediately apparent what a certain stencil mode is supposed to do. For example, if you used the constructor

StencilMode(StencilOperationFunction depthPass, StencilOperationFunction depthFail, StencilOperationFunction stencilFail, StencilCompareFunction compare, int reference, uint mask

use the following construct instead:

{
    Pass = depthPass
    Fail = stencilFail
    DepthFail = depthFail
    Comparison = compare
    CompareMask = mask
    Reference = reference
}

The (adaptive) pipeline state is encapsulated in four new types:

• BlendState
• DepthState
• StencilState
• RasterizerState

Unless you manually construct render objects, you will probably set their fields by using new and changed functionality in the Sg module. These changes include:

• Blend modes can now be set separately for each color attachment. To this end, there exist two functions:

  • Sg.blendMode : aval<BlendMode> -> ISg -> ISg
  • Sg.blendModes : aval<Map<Symbol, BlendMode>> -> ISg -> ISg

  The former sets the global blend mode (as usual), whereas the latter allows the user to specify a blend mode for each attachment. The blend modes defined for an attachment take precedence over the global blend mode, which is used as a default value if the map does not contain an entry for an attachment. Furthermore, it is now possible to set the blend constant with Sg.blendConstant : aval<'a> -> ISg -> ISg where 'a can be any type that is compatible with C4f.

• Color write masks make it possible to specify which color channels are written to a buffer. The same semantics as for blend modes are used:

  • Sg.colorMask : aval<ColorMask> -> ISg -> ISg
  • Sg.colorMasks : aval<Map<Symbol, ColorMask>> -> ISg -> ISg

  Moreover, there are some utility functions to disable and enable color output altogether:

  • Sg.colorWrite : aval<bool> -> ISg -> ISg
  • Sg.colorWrites : aval<Map<Symbol, bool>> -> ISg -> ISg
  • Sg.colorOutput : aval<Set<Symbol>> -> ISg -> ISg

  Internally, these functions set the color write masks to either ColorMask.All or ColorMask.None.

• The depth state can be controlled with the following functions:

  • Sg.depthTest : aval<DepthTest> -> ISg -> ISg
  • Sg.depthBias : aval<DepthBias> -> ISg -> ISg
  • Sg.depthWrite : aval<bool> -> ISg -> ISg
  • Sg.depthClamp : aval<bool> -> ISg -> ISg

  The DepthTest type no longer controls whether depth clamping is active, but only determines the applied comparison function.

• The stencil state can now be controlled separately for front- and back facing polygons (or globally as before). The functions in the Sg module let users set the StencilMode and the write masks.

• Sg.writeBuffers : aval<Set<Symbol>> : ISg -> ISg is now adaptive and a utility function that calls Sg.depthWrite, Sg.stencilWrite and Sg.colorOutput internally.

• The aforementioned functions (and more) now have non-adaptive counter-parts (E.g. Sg.blendMode' : BlendMode -> ISg -> ISg)

GPU queries

The IRuntime interface now provides methods for creating GPU queries that can be passed to render tasks and compute programs to gather various statistics. Refer to the example (32 - Queries) to see how it works.

Semantic changes in IRuntime.CompileClear

This release adds the possibility to explicitly clear the stencil attachment via IRuntime.CompileClear overloads. Previously, the stencil buffer was implictly cleared to 0 whenever a depth clear value was provided. Users relying on this behavior will now have to provide a stencil clear value explicitly.

Additionally, overloads that only specify a single color will now clear all color attachments to the specified value. Previously, only the attachment with name DefaultSemantic.Colors was cleared (if existent).

Adaptive resources

Previously the interface IOutputMod and the related abstract class AbstractOutputMod were used to implement custom adaptive resources. This version comes with additional overloads for creating resources in the IRuntime interface, which should cover the most common use cases that were missing until now. If you have a use case that is not implemented yet, don't hesitate to open an issue on Github.

For the remaining, more specific use cases that don't justify a dedicated IRuntime method, you can continue using the aforementioned types. They have been renamed to IAdaptiveResource and AdaptiveResource respectively.

Rework of low-level texture API

Texture creation

Previously, the IRuntime interface provided the following low-level functions to create textures:

// General API
abstract member CreateTexture : size : V3i * dim : TextureDimension * format : TextureFormat * slices : int * levels : int * samples : int -> IBackendTexture

// Specialized API for 2D and cube textures
abstract member CreateTexture      : size : V2i * format : TextureFormat * levels : int * samples : int -> IBackendTexture
abstract member CreateTextureArray : size : V2i * format : TextureFormat * levels : int * samples : int * count : int -> IBackendTexture

abstract member CreateTextureCube      : size : int * format : TextureFormat * levels : int * samples : int -> IBackendTexture
abstract member CreateTextureCubeArray : size : int * format : TextureFormat * levels : int * samples : int * count : int -> IBackendTexture

We reworked this to address three issues with this design:

• The general API does not distinguish between regular textures and texture arrays, unlike the specialized functions. Consequently, one has to pass 0 for the slices parameter to obtain a regular texture.
• There are no specialized functions for 1D and 3D textures.
• The specialized functions for 2D textures share the same name as the general API.

The new API introduced in this release looks as following:

// General API
abstract member CreateTexture      : size : V3i * dimension : TextureDimension * format : TextureFormat * levels : int * samples : int -> IBackendTexture
abstract member CreateTextureArray : size : V3i * dimension : TextureDimension * format : TextureFormat * levels : int * samples : int * count : int -> IBackendTexture

// Specialized API for all dimensions (implemented as extensions of the general API)
abstract member CreateTexture1D      : size : int * format : TextureFormat * levels : int -> IBackendTexture
abstract member CreateTexture1DArray : size : int * format : TextureFormat * levels : int * count : int -> IBackendTexture

abstract member CreateTexture2D      : size : V2i * format : TextureFormat * levels : int * samples : int -> IBackendTexture
abstract member CreateTexture2DArray : size : V2i * format : TextureFormat * levels : int * samples : int * count : int -> IBackendTexture

abstract member CreateTexture3D      : size : V3i * format : TextureFormat * levels : int -> IBackendTexture

abstract member CreateTextureCube      : size : int * format : TextureFormat * levels : int -> IBackendTexture
abstract member CreateTextureCubeArray : size : int * format : TextureFormat * levels : int * count : int -> IBackendTexture

How to transition: If you create your textures manually, it will most likely be enough to just replace all occurrences of CreateTexture and CreateTextureArray with CreateTexture2D and CreateTexture2DArray respectively. If you used the general API before (e.g. for 3D textures), you probably want to use the specialized functions instead. These have the advantage that they only expose parameter combinations that make sense (e.g. 1D and 3D textures do not support multisampling). Just note that the parameter order of the old CreateTexture is different from the new API.

Output views

The typesIBackendTextureOutputView and BackendTextureOutputView were deleted as they were duplicated functionality. Use the item and slicing properties of IBackendTexture, as well as the GetOutputView() methods instead.

Vulkan

The wrapper around the native Vulkan API now distinguishes between different core versions, putting the interfaces in respective modules. For example, Vulkan 1.2 core features are found in the Aardvark.Rendering.Vulkan.Vulkan12 module. This makes it easier to target a specific core version. Other changes include

• Result codes have been renamed. E.g. VkResult.VkSuccess -> VkResult.Success
• Default values of empty enums have been renamed MinValue -> None

Other changes

The following changes are not likely to be relevant for the average user:

• Deleted RunningMean -> Use AverageWindow in Aardvark.Base
• Deleted IExistentialArrayProcessor, GeometryPool2
• Removed StableSet, StableDictionary from GL backend, already in Aardvark.Base
• Removed GridCell, previously used in a Demo that is now deleted
• Removed module AttributePackingV2 in RenderObject.fs
• Deleted Ordered.fs in Aardvark.Rendering
• Removed signatureless surfaces / effects
• Deleted ChangeableResources
• RenderTo disposes of internal render tasks
• Removed obsolete BackendSurface and IRuntime.AssembleEffect
• [Vulkan] All resources are reference counted, implementing IDisposable. Removed delete functions (e.g. Image.delete, Device.Delete(Image))
• [Vulkan] Deleted unused Management/ResourcesNew.fs
• Moved ReferenceCountingSet to Aardvark.Base
• Removed broken Sg.overlay and related types
• [Vulkan] Added conservative rasterization
• Rename Sg.diffuseFileTexture' -> Sg.diffuseFileTexture
• Removed unused overrides and images from OutputDescription
• Removed unused images from IFramebufferSignature and IFramebufferRuntime.CreateFramebufferSignature+
• Removed unused CustomResource and Resource.custom from Vulkan backend
• Adaptive Sg texture functions now accept any subtype of ITexture (e.g. aval<IBackendTexture>)
• RenderTo returns IBackendTexture
• IRuntime.CreateFramebuffer(signature : IFramebufferSignature, textures : Set<Symbol>, size : aval<V2i>) changed to IRuntime.CreateFramebuffer(signature : IFramebufferSignature, size : aval<V2i>, writeOnly : Set<Symbol>)
• IRuntime.CreateFramebuffer(signature : IFramebufferSignature, size : aval<V2i>) creates write-only attachments for depth and stencil now.
• Added methods to render to cube maps
• GL / Vk MSAA + Depth and Stencil download
• Cleanup of driver info reporting
• [GL] allow configuration of depth range using Config.DepthRange (see Issue #66)
• Improved single value uniform applicators: implemented SingleUniformHolder
• Added C# Sg overloads for VertexAttribute and VertexIndices
• Changed FShade Tangent/Binormal semantics to follow common convention: tangent=DiffuseColorUTangents; binormal=DiffuseColorVTangents

Media 5.1

• Added missing typed variants of Sg primitives. This will likely lead to warnings regarding "superfluous use of Sg.noEvents"
• Updated CEF to 87.0.4280