Aardvark 5.2 changelog

Aardvark 5.2 changelog

This release focuses on Aardvark.Base and Aardvark.Rendering, tidying up the API but also bringing new features such as Raytracing with Vulkan. This document is mainly intended as a reference to make the process of porting from 5.1 to 5.2 easier for developers.

Base 5.2

• Added various float32 variants for geometry types (e.g. Ray3f, Plane3f, ...). Some functions provide default epsilon values. These might not be optimal for the new float32 overloads.
• Other changes to geometry related types include:
  • Removed IBoundingRange1d (was unused)
  • Added IBoundingBox* and ISize* for other primitive types. Box* and vector types implement only their corresponding interfaces. E.g. Box2i implements ISize2i instead of ISize2d. Additionally, all box types implement IBoundingCircle2* or IBoundingSphere3*.
  • Renamed Box3d.GetBoundingSphere3d() to Box3d.BoundingSphere3d
  • Renamed Box2d.GetBoundingCircle2d() to Box2d.BoundingCircle2d
  • Removed DistanceScale from Cylinder3d. Added an overload for ray - cylinder intersection that accepts a distance scale parameter if this functionality is needed.
  • Renamed Quadric to QuadricD
  • Renamed static class Orthogonalism to Orthogonality
  • Removed static class GeometricProperties. Extension methods moved to Polygon2dExtensions
• Added Aardvark.Half, a C# implementation of float16
• Added Fun.PowerOfTwo overloads, changed return type from int64 to uint64. This change was made since the returned value cannot be negative and the exponent can be up to 63 now (previously 62).
• Removed aliases of basic vector operators (e.g. V3d.Add())
• Fixed and simplified SRTPs of FSharpMath functions (may require some new explicit members on custom types now). This change fixes some scenarios in which code would not compile to due ambiguities.
• Removed <, >, >=, <= for matrices, instead implemented Mat.AllSmaller(), Mat.AnySmaller(), and so on.
• Removed Fun.Lerp overloads mixing decimal with float and double.

Media 5.2

• Removed obsolete RenderCommand in Aardvark.UI. Use the identically named type from Aardvark.SceneGraph instead.

Rendering 5.2

• Added initial support for raytracing using Vulkan raytracing extensions. Refer to the example (36 - Raytracing) to see how it works.
• Removed RenderbufferFormat, use TextureFormat instead. Also removed unsized texture formats (e.g. TextureFormat.Rgba) and obsolete GL specific ones (e.g. TextureFormat.DualAlpha8Sgis). Replace unsized texture formats with specific ones, for example:
  • Rgb → Rgb8
  • Rgba → Rgba8
  • DepthComponent → DepthComponent32f
  • DepthStencil → Depth24Stencil8
• Reworked how framebuffer signatures are defined:
  • The order of color attachments can be declared explicitly. Previously, the layout was always computed based on semantics order.
  • Depth and stencil attachments are merged into a single attachment. Separate depth and stencil attachments are not supported by Vulkan at all, and hardware support with GL seems to be rare as well. This simplifies some internal code. The following changes have to be taken care of:
    • DefaultSemantic.Depth and DefaultSemantic.Stencil are now obsolete and aliases for DefaultSemantic.DepthStencil
    • Sg.writeBuffers no longer accepts set<Symbol> as parameter, but set<WriteBuffer> where WriteBuffer is defined as:

      type WriteBuffer =
          | Color of Symbol
          | Depth
          | Stencil

  • The samples parameter has been moved from the first position to the second one. This makes it possible to define it as an optional parameter (default is 1). Previously, two overloads were provided to emulate this behavior: runtime.CreateFramebufferSignature(samples, attachments, ...) → runtime.CreateFramebufferSignature(attachments, samples, ...)
  • The sample count is now a parameter of the signature rather than the individual attachments. Therefore, the following style of attachment definitions can be simplified: DefaultSemantic.Colors, { format = TextureFormat.Rgba8; samples = samples } → DefaultSemantic.Colors, TextureFormat.Rgba8
• Resolved some remaining issues with the texture creation API:
  • Adaptive overloads had a different parameter order than non-adaptive variants. The adaptive overloads follow the "normal" convention now. This should result in build errors, please review the parameter order in those cases anyways.
  • The sheer number of adaptive overloads rendered autocomplete ineffective. The more exotic overloads have been removed.
  • Cube texture overloads with samples parameter were useless, since cube textures cannot be multisampled. These have been removed.
  • Dimension specific overloads passed weird sizes to the main function. Now the size parameter strictly follows the Vulkan specification. E.g. a 1D size must be V3i(w, 1, 1) with w > 0.
• Improved how clear values are specified:
  • Now the ClearValues record and its expression builder clear should be used when per-attachment color values are required (includes a C# friendly API in Aardvark.Rendering.CSharp). Previously, an overwhelming number of overloads for these interface methods provided flexibility in how clear values could be defined. With this change, the complexity of defining arbritrary combinations of clear values is moved to the ClearValues record and its expression builder. Most of the overloads have been removed, only a handful of frequently used overloads remain, resulting in a cleaner interface.
  • Specifying color values for textures with integer formats is supported now.
  • Method IRuntime.ClearColor for clearing textures has been renamed to IRuntime.Clear to be consistent with the framebuffer clearing methods.
• Made parameter order of adaptive runtime.CreateRenderbuffer overloads consistent with base overload.
• Adjusted parameter order of IRuntime.Download and IRuntime.Upload methods. The PixImage and PixVolume parameters are moved to the second position. This way the level, slice, and offset parameters can be optional with default values. Previously, extension methods were used to emulate the optional parameters, cluttering the API. The same changes were made to DownloadDepth and DownloadStencil.
• Renamed IRuntime.Copy methods for textures (and changed parameter order). These methods are actually used to download and upload textures, and had an inconsistent parameter order:
  • Copy : NativeTensor4<'a> * ... * ITextureSubResource * ... → Upload : ITextureSubResource * NativeTensor4<'a> Signature is now consistent with basic texture upload functions, format parameter has been removed.
  • Copy : ITextureSubResource * ... * NativeTensor4<'a> * ... → Download : ITextureSubResource * NativeTensor4<'a> Similar to above, format parameter has been removed.
  • Copy : PixVolume * ITextureSubResource * ... → Upload : ITextureSubResource * PixVolume * ...
  • Copy : ITextureSubResource * ... * PixImage * ... → Download : ITextureSubResource * PixImage * ...
  • Copy : ITextureSubResource * ... * PixVolume * ... → Download : ITextureSubResource * PixVolume * ...
• Renamed ITextureSubResource.CopyTo methods:
  • CopyTo : PixImage -> unit renamed to Download
  • CopyTo : PixVolume -> unit renamed to Download
• Improved ManagedPool and related types:
  • ManagedPool now implements IDisposable. Previously, resources of the pool had to be freed by tracking and disposing each allocated ManagedDrawCall individually. With this change, the resources can also be freed by simply disposing the pool.
  • Renamed fields of AdaptiveGeometry and GeometrySignature. The field names are now uppercase, instance attributes are no longer referred to as uniforms.
  • Added ManagedDrawCall.empty
• Unified debugging flags and tools. Debugging and logging tools used to be hidden behind various flags and switches, which also were backend specific. Now a single value of the enum DebugLevel passed to the application constructor, determines which debugging tools are enabled and how much information is logged. Currently, there are four levels None, Minimal, Normal, and Full. Note that Full enables features that signifcantly impact performance. In turn, this means the following flags / settings have been removed or abstracted away:
  • The type BackendConfiguration does not exist anymore. Instead IRuntime.CompileRender has a boolean debug parameter that controls if the debug implementation of the GL render task is used. If the debug level is Full then the debug parameter defaults to true, and false otherwise. For controlling resource sharing, the variables ShareBuffersBetweenTasks and ShareTexturesBetweenTasks have been added in GL.RuntimeConfig.
  • GL.Config.CheckErrors is now internal and controlled via the debug level.
  • Vulkan.DebugConfig has been removed. Handle tracing is enabled if the debug level is set to Full.
• Reworked RenderToken and GPU queries:
  • The render token also allows passing of GPU queries now. Thus, IRenderTask no longer accepts an explicit IQuery parameter but has the pre 5.1 signature again.
  • Removed unused / unsupported RenderToken members UpdateSubmissionTime, UpdateExecutionTime, DrawUpdateTime, DrawSubmissionTime, DrawExecutionTime.
  • Removed PrimitiveCount, use a GPU query instead.
  • GPU queries now properly support post-processing effects, i.e. render tasks that are run via adaptive resource updates.
• Removed direct DevIL dependency. DevIL was used for block-compressed texture upload. This functionality is replaced with our own implementation:
  • Upload BC1-5 data from DDS files directly
  • Download (i.e. decode) compressed textures into a PixImage
  • On-the-fly compression is not implemented at the time of writing. E.g. the wantCompression field in TextureParams is ignored for PixTexture2d and FileTexture. This will be implemented in the hopefully not too distant future. For the time being, loading a compressd DDS file or using an INativeTexture are the only options to upload compressed textures.
• TextureAspect is a bit field now
• Improved Aardvark.Application.Slim (GLFW) implementation
• Moved GL.Config.UseNewRenderTask to GL.RuntimeConfig.UseNewRenderTask
• Added CLIMutable attributes instead of using mutable record fields.
• Added automatic conversions between color types and vectors
• Renamed RenderTask.ofMod to RenderTask.ofAVal
• Renamed ModRenderTask to AdaptiveRenderTask
• [GL] Reworked texture download, upload and copy code.
• [GL] Made OpenGL 4.6 default
• [GL] Moved extension functions from GL to GL.Dispatch to avoid accidental shadowing (especially for the DSA functions)
• ResourceAccess is a bit field now
• [Vulkan] Unified and fixed synchronization barrier flags
• [Vulkan] Made fields of resources immutable where possible
• [Vulkan] Merged Shader into ShaderModule
• [Vulkan] Removed ImageAspect, use TextureAspect instead