MethaneKit Versions Save

This release adds support of Vulkan RHI on MacOS via MoltenVK framework and fixes some portability and stability issues. Vulkan RHI now supports monolithic pipeline state objects (PSO) and drops VK_EXT_EXTENDED_DYNAMIC_STATE extension requirement, which is made optional, but still used upon availability. VK_KHR_SYNCHRONIZATION_2 extension requirement was also dropped to improve portability. Some newly discovered issues reported by Vulkan validation layer were fixed as well as many stability issues.

Tutorials

• All tutorials can build with Vulkan RHI on MacOS and are tested to run normally on MacOS.
• All tutorials were cleaned up from memory errors and can run successfully with Memory Address Sanitizer enabled in build options for all APIs and platforms.
• Replaced IndexedName function with explicit fmt::format.

Graphics libraries

• Vulkan extension VK_EXT_EXTENDED_DYNAMIC_STATE was made optional by supporting monolithic vk::Pipeline state object in Vulkan::RenderState RHI implementation. Both monolithic and dynamic pipeline state APIs are supported now, depending on extension availability.
• Removed VK_KHR_SYNCHRONIZATION_2 extension requirement, as it was used to fix some minor validation layer warnings appearing only on Linux platform. Warning were muted, as not important.
• Added Vulkan RHI support on MacOS via MoltenVK with a workaround of MoltenVK bug by disabling timeline semaphore values attached to vk::SubmitInfo in vk::Queue::submit call (see FIXME comment in Vulkan::CommandListSet::Execute()). All tutorials can now run on MacOS using Vulkan RHI.
• Fixed memory corruption and occasional crash on Linux on attemp to set debug name for surface using vkSetDebugUtilsObjectNameEXT in Vulkan::RenderContext. It is not possible to set debug name for surface because it is not created with devide object, unfortunately Vulkan validation layer does not report this error but simply corrupts memory, which is resulting in undefined behaviour.
• Improved Vulkan::RenderContext frame synchronization reliability by adding vk::Fence wait of the previously acquired images before aquiring next frame image.
• Added support of ErrorSurfaceLostKHR on acquireNextImageKHR by recreating surface and swap-chain in Vulkan::RenderContext.
• Fixed Vulkan::CommandList and Vulkan::ParallelRenderCommandList command buffers invalidation on render pass updates, for example during swap chain resize.
• Fixed Vulkan::ParallelRenderCommandList debug groups encoding validation error.
• Fixed Vulkan::CommandListSet execution wait for frame image availability semaphore, when it submits ParallelRenderCommandList.
• Fixed Vulkan thread-safety issues found in "Parallel Rendering" tutorial on vk::DescriptorSet setup.
• Fixed race in multi-threaded access to CommandListSet shared pointers in Base::CommandQueueTracking.
• Fixed invalid Vulkan buffer size alignment resulting in heap memory overrun.
• Fixed DirectX applications crash on startup from Profiling build in case when COPY command queue does not support timestamp queries (on AMD Radeon integrated graphics).
• Removed explicit BufferSettings::size alignment by 256 bytes in RHI/IBuffer.h/cpp, but do it implicitly inside DirectX RHI implementation.

External libraries

• VulkanHeaders library was updated to v1.3.251
• Catch2 was updated v3.1.0 -> v3.4.0,
• CLI11 was updated v2.2.0 -> v2.3.2,
• CMRC was updated v2.0.1 -> v2.0.2,
• CPM was updated v0.38.0 -> v0.38.2,
• FMT was updated v8.1.1 -> v10.0.0,
• FTXUI was updated v4.0.0 -> v4.1.1
• ITT Api was updated v3.23.0 -> v3.24.2
• MagicEnum was updated v0.8.0 -> v0.9.3
• TaskFlow was updated v3.4.0 -> v3.6.0
• STB was updated 2021-09-10 -> 2023-01-29

Build

• Added new CMake option METHANE_MEMORY_SANITIZER_ENABLED to enable build with memory address sanitizer.
• Added MacOS_VK_Release job to CI Build workflow, which builds Methane Kit with Vulkan RHI on MacOS using static linking with MoltenVK framework from Vulkan SDK.
• Added optional step to CI Build jobs "Install Vulkan SDK", which is currently required for MacOS_VK_Release job only to link with MoltenVK framework.
• Disabled some CI Build steps and workflows in Forked GitHub repositories to let CI pass successfully for pushes.
• Updated GitHub Action sonarcloud-github-c-cpp to v2 in "CI Scan" workflow. Sonar Scanner was upgraded from v4.8 to v5.0 as well.
• Allow CI Build workflow to run in forks by removing cron schedule (GitHub automatically disables all workflows with CRON schedule in Forked repositories).
• Prevent CI Sonar Scan and CI CodeQL workflows to run in forked repositories.

[!NOTE] For MacOS users: In case of error "App Is Damaged and Can't Be Opened" on attempt to run bundled application, try removing application from quarantine using the following command:

sudo xattr -d com.apple.quarantine MethaneHelloTriangle.app
open MethaneHelloTriangle.app

This release adds initial support of compute pipeline in Methane Kit for app Graphics RHI backends (DirectX 12, Vulkan and Metal). "Console Compute" tutorial was added to demonstrate it on example of Conway's Game of Life implemented in compute shader used from pure-console application. Graphics RHI was partially covered with initial set of unit-tests implemented using "Null RHI" backend for testing of the Base RHI logic.

Tutorial applications

• Console Compute tutorial was added to demonstrate GPU compute pipeline on Conway's Game of Life example implemented in pure-console application with FTXUI library.

Graphics libraries

• New Graphics RHI classes were added to support compute pipeline (close #8):
  • ComputeContext
  • ComputeCommandList
  • ComputeState
• Added ShaderType::Compute shader type support.
• Added CommandListType::Compute support in CommandQueue.
• Added DeviceCaps::compute_queues_count.
• Added Unordered Access View support in ProgramBindings for reading and writing texture data from compute shader.
• Added Texture and Buffer read-back support via GetData methods.
• Removed common GetData and SetData methods from base interface IResource in favour of separate methods added in the derived IBuffer and ITexture interfaces to differentiate argument types and get rid of unwanted methods in ISampler interface.
• IResource methods GetSubresourceCount and GetSubresourceDataSize methods were moved to ITexture interface.
• Fixed some DirectX and Vulkan validation warnings.

User Interface

• Fix rare crash on text mesh update.

Data libraries

• FpsCounter interface and implementation was moved from Graphics/RHI to Data/Primitives to allow using it independently from RHI RenderContext.
• Enable Chunk copy and move constructors and operators.

Tests

• Initial unit-tests were added for "Graphics RHI" layer, implemented using "Null RHI" backend (continue #122):
  • Shader Test
  • Sampler Test
  • Fence Test
  • CommandQueue Test
  • ComputeState Test
  • Texture Test
  • ProgramBindings Test
  • TransferCommandList Test
  • Program Test
  • ComputeContext Test
  • Buffer Test
  • ComputeCommandList Test
• Overall code coverage has reached 30% for Modules directory.

External libraries

• FTXUI library v4.0.0 was added
• HLSL++ was updated to v3.3.1
• CPM.cmake was update to v0.38.0
• Tracy was updated to v0.9.1

Build

• Cleaned up root CMakeLists.txt
• Build with new Xcode 14.3 was supported by cleaning up the code from removed deprecated functions.
• Apple deployment target versions were bumped to use new shader reflections API:
  • MacOS 10.15 -> 13.0
  • iOS 15.0 -> 16.0

Continuous Integration

• Fixed reporting of failed unit tests: previously builds were terminating on any test failure, now builds are still failing by unit-tests but they perform all reporting operations.
• Sonar-scan build is now automatically finding all test result xml files.
• Added CodeCove components and excluded Tests and Apps directories from code coverage results.

Documentation

• ReadMe documentation was added for "Console Compute" tutorial.
• Update code in other tutorials documentation to reflect changes in Resource, Buffer and Texture methods.

[!NOTE] For MacOS users: In case of error "App Is Damaged and Can't Be Opened" on attempt to run bundled application, try removing application from quarantine using the following command:

sudo xattr -d com.apple.quarantine MethaneHelloTriangle.app
open MethaneHelloTriangle.app

This is a refactoring release which replaces monolithic "Graphics Core" module with modular RHI (Rendering Hardware Interface) consisting of interfaces, base implementation, DirectX, Vulkan, Metal and Null backend modules and new "Impl" module with PIMPL classes providing convenient way to use RHI with an extra performance boost from inlining API calls directly to final implementation, instead of virtual calls made through abstract interfaces. See performance comparison of FPS in Methane Asteroids benchmark with 3 implementations (all compiled with the same updated compiler optimization flags): v0.7.0 RHI virtual interfaces, v0.7.1 RHI PIMPL classes without inlining and with inline calls to final implementation. All tutorials, graphics primitives and user interface classes were rewritten to use RHI PIMPL classes, which allow to reduce code complexity and improve readability.

Graphics libraries

• RHI PIMPL classes were added as an alternative to using RHI abstract interfaces in your application (see Modules/Graphics/RHI/Impl). PIMPL classes are more convenient to use since they allow to write code without smart pointers and allow to get more performance with final implementation inlining. CMake option METHANE_RHI_PIMPL_INLINE_ENABLED enables RHI final implementation inlining for PIMPL classes and allows to make direct calls to final RHI implementation without virtual call overhead. PIMPL inlining can gives up to 5% of extra performance in highly loaded rendering scenario.
• Graphics Core module was renamed to Graphics RHI (RHI is a common acronym for Rendering Hardware Interface) and split into several CMake modules Interface, Base, DirectX, Vulkan, Metal and Impl - this makes architecture even more modular and extensible.
• All RHI abstract interfaces were renamed to start with I prefix in file and struct names and put under Methane::Graphics::Rhi namespace, for example Graphics::Device -> Graphics::Rhi::IDevice.
• All RHI implementation classes were symmetrically renamed by removing impl. suffix and moving it under impl. namespace, for example Graphics::DeviceBase -> Graphics::Base::Device, Graphics::DeviceDX -> Graphics::DirectX::Device. Source files were renamed accordingly: Graphics/DeviceBase.h -> Graphics/Base/Device.h, Graphics/DeviceDX.h -> Graphics/DirectX/Device.h. This allows to mirror RHI implementations for different APIs with completely symmetrical classes and files naming inside different namespaces.
• Removed excessive Create static factory functions of ITexture and IBuffer interfaces using custom setting initialisers.
• Add sequential CreateX virtual methods in RHI interfaces and use them in implementation of X::Create static factory functions.
• Added RHI Null implementation which is going to be used in unit tests.
• BLITCommandList was renamed to TransferCommandList.
• QueryBuffer was renamed to QueryPool.
• Replaced std::string with std::string_view in IObject::SetName and GetName methods.
• Simplified implementation of Buffer and Texture classes for Vulkan and DirectX APIs by replacing template class variants with common class implementation.
• Migrated ImageLoader, ScreenQuad and SkyBox to use RHI PIMPL classes instead abstract interfaces and implemented themself in PIMPL style.
• Split MeshBuffers template class implementation to MeshBuffersBase class and derived template class.
• Some headers from Primitives modules were moved inside RHI submodules:
  • Moved Windows/DirectXErrorHandling.h to RHI/DirectX module and renamed to ErrorHandling.h.
  • Moved FpsCounter.h and split to interface and implementation to RHI/Interfaces and RHI/Base modules.

User Interface

• Migrated Font, Text and Badge classes to RHI PIMPL classes instead of abstract interfaces and implemented themself in PIMPL style.

Platform libraries

• Fixed X11 window resizing on Linux with Nvidia drivers: ErrorOutOfDateKHR after resizing swap-chain on Linux with NVidia proprietary drivers (close #105)
• Platform/Input module was split into to submodules: Keyboard, Mouse, Controllers and ActionControllers. All classes from this modules were moved under Platform::Input namespace.

Data libraries

• Added Data::EnumMask<EnumType> template class implementing bit-mask operations on enum values used as bits. EnumMask type is used in Methane Kit public interfaces instead of magic_enum::bitwise_operators.
• Added Data::Transmitter<ICallbackType> class which implements Data::IEmitter by transmitting callback connections to some other emitter instance.

External libraries

• CPM.cmake was updated to v0.37. This release fix parallel cmake generation for multiple configuration used in CLion.
• Tracy was updated to v0.9.
• DirectX-Headers was updated to v1.608.2b to use modular headers instead of monolithic d3dx12.h in DirectX RHI.

Tutorials applications

• All tutorial implementations were rewritten to use RHI PIMPL classes instead of smart pointers to abstract interfaces. It allows to reduce code complexity and make it looks clean and simple.

Tests

• Added unit tests for class from Data/EnumMask.hpp.
• Added unit tests for functions from Data/EnumMaskUtils.hpp.
• Added unit tests for class from Data/Transmitter.hpp

Builds

• Tracy executable file is automatically added in "Profile" build artifacts (pre-platform executables are taken from Methane Powered Tracy releases).
• Enabled aggressive optimisations in Release builds, including whole program optimisations with link-time code generation, inline functions expansion, disable security checks and others.
• ITT instrumentation is disabled by default in Release builds, but still enabled in Profile builds.
• Add explicit CMake options printing during configuration.
• Windows builds in GitHub Actions are upgraded to use Visual Studio 2022.
• Dependent GitHub actions were updated in yaml scripts to use NodeJS 16.
• CI Sonar Scan builds now use new GitHub action sonarcloud-github-c-cpp to install scanner binaries. build-wrapper tool is not used anymore, it was replaced with Ninja compilation data base generated by CMake.

Documentation

• Tutorials README documentation was updated to reflect PIMPL RHI classes usage instead of pointers to abstract interfaces.
• Added Data, Platform, Graphics and UserInterface modules dependency diagrams in folder README.md files using Mermaid markdown.
• Updated High-Level Architecture diagram, RHI classes diagram and GraphViz module relations diagram.

Release CI Runs

• Build v0.7.1.305
• Sonar Scan v0.7.1.300
• CodeQL Scan v0.7.1.40

iOS and tvOS platforms support was added in this release.

• Tutorials applications:
  • Customised default UI options to make HUD visible by default on iOS.
  • Added iOS screenshots for tutorials.
  • Added keyboards shortcuts for tutorials in README files.
  • Known issue: #101
• Platform libraries:
  • Methane::Platform::AppIOS implementation was added to support iOS and tvOS mobile platforms (closed #12).
  • iOS Alert window implementation was added.
  • Limited input support was added for iOS to translate touches to mouse events (keyboard input is not supported).
  • Moved RenderContext::GetContentScalingFactor and RenderContext::GetFontResolutionDpi methods to Platform::IApp interface with platform dependent implementations. Linux implementation for X11 was added.
• Graphics libraries:
  • Manual memory management was removed from Objective-C Metal graphics implementation due to switching to ARC (automatic reference counting).
  • RenderCommandList::Draw and DrawIndexed calls implementation for Metal was changed to exclude using of start_vertex and start_instance parameters for GPU Family < MTLGPUFamilyApple3 or MTLGPUFamilyMac2, which is essential for working on iOS Simulators.
  • Unsupported Sampler parameters were put under #ifdef APPLE_MACOS to enable tvOS support.
  • Fixed flipping camera projection up-side-down in portrait orientation.
• Tests infrastructure:
  • Add missing test targets to GCov coverage on Ubuntu.
• Build infrastructure:
  • Added CI Build & Test system based on GitHub Actions, which is partially duplicating CI in Azure Pipelines, but enables CI in forked repositories.
    • Fixed shaders code signing by DXC in GitHub agents environment by adding hardcoded path to DXIL.dll in DXC environment.
  • Added Externals/iOS-Toolchain.cmake file from iOS-CMake project to enable iOS & tvOS build configuration.
  • Apple Clang is now used with ARC enabled (automatic reference counting) via -fobjc-arc option.
  • Split MacOS and iOS application .plist configs generation via CMake/MethaneApplication.cmake
  • Split CMake/MethaneGlobalOptions.cmake from CMake/MethaneBuildOptions.cmake to allow including it in the root CMakeLists of external projects to properly set global CMake options.
  • Add support for Apple code signing via APPLE_DEVELOPMENT_TEAM cmake option.
  • Extended Build/Unix/Build.sh script to support iOS / tvOS builds via new command-line arguments --apple-platform, --apple-dev-team and --apple-deploy-target.
  • Added iOS and tvOS configurations to CMakePresets.json.
  • Added iOS and tvOS Simulator builds in Azure Pipelines.
  • Added CLion cmake configurations for iOS.
  • Added iOS and tvOS build instructions to Build/README.md.
  • Fixed iOS app running natively on Mac with Apple Silicon, thanks to @andrejnau for solution of issue #101

Vulkan API and Linux platform support was added in this release:

• Tutorials applications:
  • HelloTriangle tutorial was simplified with removal of vertex buffer and using only vertex_id for triangle rendering.
  • HelloCube tutorial was added for demonstration of rotating colored cube rendering using only vertex and index buffers. Uniform buffers and program bindings are not used for the purpose of simplicity and vertices transformation is done fully on CPU. HelloCubeUniforms tutorial version (under UNIFORMS_BUFFER_ENABLED define) implements vertices transformation on GPU using MVP matrix stored in uniforms buffer and program bindings object.
  • CubeMapArray tutorial was added to demonstrate cube-map array texturing, rendering to texture sub-resource views and Sky-box rendering with Methane graphics extension.
  • ParallelRendering tutorial was added to demonstrate multi-threaded render commands encoding to a single render pass.
  • TextureLabeler helper class was added to library MethaneAppsCommon with shared implementation of text labels rendering to texture cube/array faces.
• Samples applications:
  • Asteroids sample was moved to MethaneAsteroids repository for demonstration of Methane Kit external usage.
  • Scene complexity in Asteroids sample can be changed now with new single-key shortcuts: 0 .. 9
• Data libraries:
  • Add initial thread-safety to Events library in Emitter and Receiver classes.
  • Fixed ITT instrumentation issue related to access to uninitialised domain global variable at application initialisation from other global variable initialisers.
• Platform libraries:
  • Platform::AppLin implementation based on X11/XCB libraries for Linux was added (close #11), which allows to create GUI Window for rendering on Linux desktop with support of:
    • Window resizing and full-screen mode.
    • Keyboard and Mouse events translation.
    • Message box with text message and buttons drawing via X11/XCB.
    • Window icon loaded from PNG resources.
  • Command line help and parsing errors are now printed to the console output, instead of showing in message box.
  • Input::Keyboard::State and Input::Mouse::State conversion to string was fixed, more functionality of these classes was covered with unit tests.
  • Fixed Linux application window placement in multi-monitor configuration.
  • Fixed MacOS window settings setup from command line.
• Graphics libraries:
  • Graphics Core library changes:
    • Vulkan-based Graphics Core implementation was added (closed #10): SystemVK, DeviceVK, RenderContextVK, FrameBufferTextureVK, RenderPassVK, RenderPatternVK, ShaderVK, ProgramVK, RenderStateVK, ViewStateVK, CommandListVK, RenderCommandListVK, FenceVK, BufferVK, FrameBufferTextureVK, DepthStencilTextureVK, RenderTargetTextureVK, ImageTextureVK, SamplerVK, ProgramBindingsVK, ResourceBarriersVK, ParallelRenderCommandListVK, TimestampQueryBufferVK, TimestampQueryVK. classes.
      • Vulkan API is used via vulkan.hpp C++ wrappers with support of dynamic dispatch table, which allows to build without Vulkan SDK libraries. vk::Unique* wrappers are used to automatically release Vulkan objects in RAII style.
      • Vulkan debug utils messenger instance is used to track validation layer message and fixed a lot of them. A few minor validation warnings were ignored in callback function in DeviceVK class.
      • Vulkan object names and debug labels are used extensively for all Vulkan objects.
      • RenderCommandListVK setup all Vulkan pipeline barriers before render pass begin by using secondary command buffer for recording all synchronisation commands separately from render pass commands in primary buffer.
      • ImageTextureVK has mip-maps generation implemented on GPU.
    • RenderPattern class was added to represent render pass attachments configuration without binding to particular resources (wrapper of vk::Renderpass). RenderPass was updated accordingly to get configuration from RenderPattern and bind attachment resources. RenderPattern instance was added to RenderState settings.
    • Device::Capabilities struct was added with the required command queues count and other configuration flags, required due to Vulkan specifics.
    • CommandQueueTrackingBase class was added to share command queue execution tracking logic between DirectX and Vulkan implementations.
    • RenderContextDX implementation is now using waitable object to reduce DXGI swap-chain latency.
    • System singleton is now destroyed strictly after all its Devices to enable correct Vulkan destruction order.
    • ResourceState enumeration was simplified: state VertexAndConstantBuffer was split to VertexBuffer and ConstantBuffer states; states NonPixelShaderResourceand PixelShaderResource were merged into one state ShaderResource.
    • Added support for resource ownership transition between command queue families in Resource::SetOwnerQueueFamily(..) and ResourceBarriers::[Add|Remove]OwnerTransition(...) interfaces and implemented ownership transition for Vulkan resources.
    • ResourceLocation interface was renamed to ResourceView, extended with settings of sub-resource index, count, size, offset and reworked internally for DirectX and Vulkan to support multiple views handling for a single resource.
    • Added initial support of the HLSS StructuredBuffer in DirectX.
    • Resource factory functions were simplified with removal of optional DescriptorByUsage argument, which was previously used to restore DirectX descriptors after resource recreation on previous location in heaps to let bindings work.
    • Add support of debugger break and message filtering with DirectX debug layer in DeviceDX class.
    • Shared command list timestamp queries between DirectX and Vulkan using TimestampQueryBuffer and TimestampQuery objects in CommandListBase class.
    • Bug fixes:
      • Fixed Methane Tracy GPU instrumentation via Methane/TracyGpu.hpp with Tracy v0.8 (was broken after update). Added reference Tracy GPU instrumentation via TracyD3D12.hpp header under macro definition METHANE_GPU_INSTRUMENTATION_ENABLED == 2 in CommandListDX.hpp(value 1 is reserved for Methane GPU instrumentation).
      • Fixed runtime errors in GPU profiling builds with METHANE_GPU_PROFILING_ENABLED=ON:
      • Fixed DirectX GPU timestamps re-calibration issue leading to GPU ranges shifting.
      • Fixed command list execution waiting threads synchronisation in Profiling builds in Typography tutorial.
      • Fixed resources retaining in command lists. Retained resources were incorrectly cleared on CommandList::Reset(), while they should be cleared on CommandList::Commit().
      • Fixed DirectX descriptor heaps allocations after Context::Reset() by always using deferred heap allocation in all cases. Deferred heap initialisation flag was removed, since it became unconditionally deferred.
      • Fixed sporadic hang in CommandQueueTrackingBase::WaitForExecution()
      • Fixed sporadic crash on destruction of CommandQueueTrackingBase with proper shutdown procedure called from destructor of derived class.
  • Camera::Resize method arguments were changed to use FrameSize and FloatSize structures, which simplify its calls from the App::Resize method.
  • Graphics/Mesh module was split from Graphics/Primitives.
  • SkyBox extension is now using CubeMesh instead of SphereMesh for sky rendering.
• User Interface library changes:
  • Text::HorizontalAlignment::Justify mode was added to support horizontal text justification.
  • HeadsUpDisplay: Graphics API name is now displayed in HUD .
  • Fixed Text repeated buffer updates in deferred mode.
• Tests:
  • All unit tests were updated to support breaking changes in Catch v3.
  • Logging of Point, Rect and RectSize values was added in DataTypes unit tests.
• Common changes:
  • Shader uniform structures were shared between HLSL and C++ code via header files using HLSL++ library.
  • Chained parameter setters were added to some major Settings structures for initialization convenience.
• External libraries:
  • External dependencies management via Git submodules was replaced with CPM.cmake package manager. No submodules anymore - it greatly simplifies external library updates!
    • All externally dependent repositories are downloaded to CPM cache directory during CMake configuration stage, to Build/Output/ExternalsCache by default (it can be changed with CMake option CPM_SOURCE_CACHE).
    • When CMake project is configured under CLion, external repositories are downloaded to individual build directories of each configuration to workaround parallel cache update collision issue of the CPM.cmake.
  • New README.md description of the external dependencies was added in Externals directory.
  • Library updates:
    • Vulkan-Headers was updated to v1.3.219
    • SPIRV-Cross was added v1.3.216.0
    • DirectXCompiler was updated to v1.6.2104 to support SPIRV generation on Windows and new binaries for Linux
    • DirectXTex was updated to v1.9.6
    • Catch2 updated to v3.1.0
    • CLI11 updated to v2.2.0
    • CMRC updated to 2021-08-27
    • FMT updated to v8.1.1
    • FreeType2 updated to v2.12.1
    • HLSLpp updated to v3.2+ with integer division fixes
    • IttApi updated to v3.23.0
    • MagicEnum was updated to v0.8.0
    • TaskFlow was updated to v3.4.0
    • STB updated to 2021-09-10
    • Tracy updated to v0.8.2.1
    • CMakeModules updated with support for auto-detecting new Windows SDK versions, including Win11 2110 SDK (closed #87)
• Build Infrastructure:
  • Project repository, Azure Dev Ops and SonarCloud projects were moved from personal GitHub account @egorodet to the organization @MethanePowered
  • CMake changes:
    • Root CMakeLists.txt was simplified by moving all compiler configuration options to CMake/MethaneBuildOptions.cmake.
    • CMake function add_methane_application was changed to use flexible named parameters.
    • Graphics API variables definition and default API identification were moved from root CMakeList to the CMake/MethaneModules.cmake in functions get_native_graphics_apis and get_default_graphics_api for reusing in external projects.
    • Externally used variables GRAPHICS_API, DXC_BINARY_DIR, SPIRV_BINARY_DIR were added as properties to CMake target MethaneKit.
    • CMake build option METHANE_GFX_VULKAN_ENABLED was added to enable Vulkan build on Windows.
    • CMakePresets.json file was added with predefined configure and build presets for "Ninja Multi-Config" and platform native generators "Visual Studio 16 2019", "Xcode" and "Unix Makefiles".
    • Shader config files were replaced with shaders compilation functions in CMake: add_methane_shaders_source to compiler shaders file and add_methane_shaders_library to add compiled shaders to application resources (see CMake/MethaneShaders.cmake)
    • Removed Visual Studio CMake configuration file CMakeSettings.json. CMakePresets.json should be used instead.
    • CMake module MethaneShaders enable compilation of HLSL shaders to SPIRV for Vulkan graphics API using new DirectX Compiler (DXC) version.
    • Fixed tests running during build, which was broken due to missing CMake command dependency.
    • Minimum CMake version is now 3.18.
  • Azure Pipelines CI changes:
    • Azure builds are now using CMake Presets as a single source of build configurations for Release, Profile and SonarScan builds for all platforms.
    • Azure build jobs and CMake build profiles were updated for multiple graphics API support and extended with Vulkan builds for Windows.
    • Ubuntu_VK_Profiling build was added to Azure Pipelines.
    • Azure builds for Linux and MacOS are now publishing build artifacts as TAR archives to keep executable file permissions unchanged.
    • Use caching of Externals CPM package sources in Azure Pipelines and GitHub Workflows to speedup builds.
    • MacOS builders were switched from v10.15 to v11.
  • Build scripts Build/Windows/Build.bat and Build/Posix/Build.sh were extended with convenience command line options, including --vulkan, --debug, --graphviz, --analyze and others.
  • GitPod should now auto-install required Linux packages and support preview of the UI window on remote machine.
  • Removed ReSharper configuration files Folder.DotSettings and .editorconfig from repository.
  • Initial Vulkan build support on MacOS was added via MoltenVK library, unfortunately it does not work due to some unsupported Vulkan extensions which are required by Methane Kit.
  • CodeQL workflows now use Profile CMake presets same as in SonarCloud analysis builds in Azure Pipelines.
  • CodeQL analysis on Windows has started failing in GitHub actions since May 25 with IOException "There is not enough space on the disk", so analysis steps were disabled for Windows to let build pass without analysis until the issue is fixed by GitHub support.
  • Fixed GCC 11.2 build errors on Ubuntu 22.04.
  • Moved build instructions from root README.md to Build/README.md.

HLSL++ math, Graphics API optimizations, automated static code analysis, unit-tests code coverage, code improvements and extensive refactoring were done in this release:

• Samples and tutorials:
  • Migrated tutorials and samples from CML to HLSL++ vector math library with SIMD intrinsics acceleration for CPU. Removed explicit alignment of uniform structure fields, which is not required anymore for HLSL++ types, since they already use 16-bytes aligned data storage.
  • Asteroids sample was optimized with up to 50% FPS increase:
    • Uniforms buffer size was reduced by reusing scene view-projection matrix in shaders (+7% FPS)
    • Uniforms buffer data transfer is made asynchronously with draw commands encoding (+20% FPS)
    • Disabled repeated retaining of the bound resources in command list draw calls (+30% FPS)
    • Disabled automatic resource barriers setup during parallel asteroids rendering to take advantage of automatic state propagation from Common state.
    • Got rid of excessive program binding calls in DirectX as a result of using Frame-Constant argument accessors in program bindings.
• Documentation updates:
  • Textured Cube tutorial documentation was added (closed #17)
  • Shadow Cube tutorial documentation was added (closed #18)
  • Typography tutorial documentation was added
  • Platform App, Graphics App and User Interface App documentation was added
  • High-level architecture diagram was added on the project page
  • Graphics Core Interfaces diagram was added on the project page
• Common libraries:
  • Primitives library extended with error handling (closed #74):
    • Methane/Exceptions.hpp was added with common exception type defintions
    • Methane/Checks.hpp was added with error checking macro definitions aka META_CHECK*
    • META_LOG macros has been updated to make string formatting using FMT library inside of the macro using variadic arguments
• Data libraries
  • RawVector template class was added as a replacement of cml::vector for dense-packed components storage used in vertex attributes.
  • Point template class now use underlying HLSL++ vector and unifies 2D and 3D implementations.
  • Rect and RectSize, Volume and VolumeSize classes were refactored. Made class fields private, available through accessors.
  • Constants template class was added with math constants.
• Platform libraries
  • Platform App library was updated with unified error handling logic in AppBase class, moved from platform specific classes
• Graphics libraries
  • Graphics Core changes:
    • Program binding improvements:
      • Program::Argument and Program::ArgumentAccessor (previously Program::ArgumentDesc) were refactored from struct to class style with field accesor functions. Program::Argument::Modifiers bit-mask was replaced with Program::ArgumentAccessor::Type enum.
      • New program argument accessor type was added for frame-constant arguments Program::ArgumentAccessor::Type::FrameConstant to reduce number of excessive argument binding setup calls. Frame-constant bindings are properly supported by DX descriptor table layout.
      • Frame-buffer index was added to ProgramBindings::Create function as an optional argument to support frame-constant bindings.
      • Applying of DirectX resource states and root parameter bindings was reworked in ProgramBindingsDX.
    • Resource upload and state synchronization improvements:
      • COPY comamnd queue is now used by default for BlitCommandList execution in DirectX (instead of DIRECT command queue used before). So the resources upload is also done with a COPY queue in DX now. It can be switched back to using DIRECT queue with RenderContext::Settings::options_mask bit-mask flag Context::Options::BlitWithDirectQueueOnWindows.
      • Resource::SetData method is extended with an optional argument of command queue for resource state synchronization. Command queue where resource is actually used should be passed whenever possible.
      • Resource barriers setup was moved from the Resource::SetData method implementations to the SetProgramBindings, SetVertexBuffer and SetIndexBuffer calls, while setup resource barriers are still cached inside Resource object.
      • Resource::State and Resource::Barriers types were moved to the public header files and split from Resource interface definition.
    • CommandKit interface was added to Graphics Core to provide unified access from Context::GetDefaultCommandKit to the command queue, command lists, command list set and synchronization fences made for working together with the same CommandList::Type. This interface allowed to replace methods Context::GetUploadCommandQueue, Context::GetUploadCommandList, Context::GetUploadCommandListSet and RenderContext::GetRenderCommandQueue with Context::GetDefaultCommandKit.
    • CommandList changes:
      • CommandList::SetResourceBarriers(...) call was added to the public interface (was private before).
    • RenderCommandList changes:
      • RenderCommandList::ResetWithStateOnce method was added additionally to ResetWithState to skip command list reset when it is already in Encoding state with the same RenderState already applied.
      • RenderCommandList::SetIndexBuffers method was adedd, index buffer is now set separately from DrawIndexed call.
      • RenderCommandList::Set[Index|Vertex]Buffers methods were exnteded with an optional argument which allows to disable setting resource barriers automatically.
    • ParallelRenderCommandList changes:
      • Child render command lists are now committed in parallel.
    • ImageLoader now initializes texture names inside Load functions.
    • Changed ResourceBase derived classes hierarchy based on template implementation of Resource[DX|MT|VK]<ResourceBaseType> which is replacing ResourceNT alias class
    • Removed almost all Native platform alias headers
    • Fixed some memory leaks in Metal implementation on MacOS
    • Fixed const correctness for Device and Context references passed to core interface factory functions
  • Graphics::App template class implementation was split to Graphics::AppBase to reduce template code and speedup compilation
  • Color template class was rewritten from scratch and now can use both integer and floating point components via underlying HLSL++ vector storage
  • ArcBallCamera unit-tests were improved and uncovered some issues in tested class implementation. Issues were fixed
  • SphereMesh generation was simplified with matrix-free implementation
  • Fixed missing debug names of graphics resources (regression of previous refactoring)
  • Fixed mip-levels count in depth texture descriptor for DirectX12
  • Fixed limited rendering FPS with VSync turned OFF on Nvidia GPUs with latest drivers (Jan 2021)
  • Enabled naming of Tracy GPU contexts
• User Interface libraries
  • Unified UnitType derived classes implementation within one template class
  • Fixed bug in Text mesh generation with multiple zero characters at the end of the string
  • Text rendering is now calling ResetWithStateOnce instead of ResetWithState to minimize rendering state resets in sequence of several text blocks
• Unit-tests coverage was expanded from 5.7% to 13%:
  • RawVector, Point new template classes were covered with unit-tests.
  • Rect and RectSize, Volume and VolumeSize existing template classes were covered with unit-tests.
  • Color template class was covered with unit-tests.
  • UnitType template class was covered with unit tests.
  • UserInterface::Context class unit convertors were covered with unit tests.
  • FakeRenderContext class was added to UI unit-testing infrastructure.
  • Replaced deprecated ParseAndAddCatchTests CMake function with catch_discover_tests to fix Catch warnings.
• Global code changes:
  • Replaced CML math library with HLSL++ to improve math performance with SIMD instructions (close #78).
  • Debug logging was extended for resource barriers synchronization, render and view state parameters and cleaned up: properly used magic_enum, removed manual enum to string conversion functions, fixed logs formatting.
  • Properly implemented or enabled default generation of assignment operators, copy and move constructors for all applicable types
  • Used MagicEnum library extensively to remove enum code bloat and improve type safety with enum class types:
    • Uses enum class types for bit-masks instead of raw enum types to improve type safety.
    • Generating string names of enum values with a single line of code
    • Iterating over enum values and getting values count
  • All modules updated with fixes of static code analysis issues from SonarCloud (closed #73):
    • Replaced all explicit exception throws and asserts with META_CHECK* macroses throwing specific exception types, which simplified error checking code and fixed many issues related to non-specific exception throws across Methane code base
    • Throw undefined enum value exception in default branches of all switch blocks to fix repeated analysis issue
    • Replaced std::function usage with template arguments wherever possible to improve performance
    • Used fmt::format(...) for string formatting wherever possible project wide
    • Used magic_enum library to replace raw enum types of bit-masks to enum class types, use enum names and counts generated in compile time.
    • Uppercase literal suffixes
    • Fixed new C++17 static analysis issues:
      • Use std::map::try_emplace instead of std::map::emplace
      • Use std::byte instead of uint8_t and char for byte-access to memory buffers
      • Use structured bindings in for loops over elements of std::map
      • Use [[nodiscard]] attribute for constant methods like getters
      • Use std::string_view in some cases for input string arguments
      • Use inline initialiser statements in if and switch statements
      • Use scoped_lock instead of lock_guard
• External libraries:
  • HLSL++ library v3.0 was added
  • CML library was removed
  • FMT v7.1.3 library was added
  • MagicEnum library v0.7.2 was added
  • OpenCppCoverage Windows tool binaries were added
  • CMRC library was updated to latest version.
  • CLI11 library was updated to v1.9.1
  • Catch2 library was updated to v2.13.5
  • IttApi library was updated to v3.18.8+
  • STB library was updated to latest revision from 13 Jul 2020
  • Taskflow library was updated to v3.1.0
  • Tracy library was updated to v0.7.7
  • Removed Sonar Scanner binaries from repository: binaries are loaded from official web site now
• Build Infrastructure:
  • Speedup Methane Kit builds up to 30% with CMake precompiled headers generated once and shared across all modules (closed #67)
  • Speedup Graphics Core build with CMake Unity build which compiles multiple C++ source files in batches as one source.
  • Automated Sonar Cloud static code analysis is integrated into Azure Pipelines continuous build system. Scan results are now available with every master and develop build separately for every supported platform (closed #68)
  • Tests code coverage results collection was setup in CI with Azure Pipelines and Sonar Cloud on Windows with OpenCppCoverage tool, on MacOS with llvm-profdata and on Linux with Gcov (closed #72)
  • Do not fail build when some unit tests fail or Sonar Scanner jobs fail with error
  • Publish Sonar Scanner error reproducer to build artifacts in case of scan failure
  • Fix Sonar Scanner cache invalidation by adding plugin version to cache key
  • CodeQL static analysis was enabled with GitHub Actions workflow and results available in Security tab on repository page
  • Use MacOS 10.15 and Ubuntu 20.04 agents with GCC 9+ in Azure Pipelines
  • GitPod was switched to VSCode UI and extensions were updated
  • CMake profiles were added for CLion 2021

This release adds text layout & rendering widget, user Interface basis, integrate Tracy Profiler & add GPU instrumentation, many memory and performance optimizations, Graphics API improvements and bug fixes. It is really BIG!

• Samples and Tutorials:
  • Typography tutorial was added to demonstrate new Methane Font rendering & Text layout widget:
    • Several text blocks with pangrams in different languages are displayed and long text paragraph from "Hitchickers Guide to the Galaxy" is rendered with calligraphic font.
    • Text forward typing or backspace deleting animation (changed with D key) demonstrates incremental text mesh updates (can be switched off with U). Typing speed can be changed with = and - keys.
    • Displaying of dynamically updated font atlas badges.
    • Horizontal and vertical text alignment can be changed with H and V keys.
    • Typography tutorial runtime parameters visualisation and controls for switching parameters are supported.
  • Common application primitives added:
    • App settings configuration is moved to Methane/Samples/AppSettings.hpp for all samples and tutorials. MacOS apps now render with VSync ON, while Windows apps with VSync OFF by default.
    • SRGB gamma correction was implemented in all samples and tutorials in Apps/Common/Shaders/Primitives.hlsl. As the result this significantly improved rendered image quality in Asteroids sample (closed #58)
• User Interface libraries were added (closed #5):
  • Typography library implements fonts management and text blocks rendering classes (closed #4):
    • Font::Library implements font loading with FreeType 2 library
    • Font class is managing Font::Char glyph metrics, packing to atlas and rendering to R8Unorm texture:
      • Font atlas supports dynamic updates with incrementally added characters in runtime.
    • Text class implements rendering of text block with a given font and layout settings:
      • Unicode text support
      • Text content size calculation in text layout pass during mesh generation
      • Text::Layout settings supported:
        • Text::Wrap defines wrapping to new line by characters or by woads or no wrapping.
        • Text::HorizonAlignment with Left, Ridht and Center options.
        • Text::VerticalAlignment with Top, Bottom and Center options.
        • Note: layout settings are applicable only when Text is created or updated with non-zero rect in Text::Settings.
      • Incremental text mesh updates on appending or erasing trailing characters from string is supported.
      • Text is managing internal buffer resources on per-frame basis to perform effective text updates without affecting GPU performance and render without artefacts on previously encoded render commands.
      • All Text items reuse single instances of RenderState and Sampler objects for all Text widget instances via Object::Registry.
  • User Interface Types library added with common UI types:
    • Units enum, UnitPoint, UnitSize and UnitRect classes were added in UserInterface/Types.h to handle UI layout positions and sizes in different units (Pixels and Dots) and conversions between them.
    • UserInterface::Context is a wrapper around Graphics::RenderContext and is used for creating all UI items serving both layout and rendering functions.
    • UserInterface::Item and UserInterface::Container are base UI classes for all widgets.
  • Widgets library implements basic UI visualisations and controls
    • Panel widget implements container visualised as semi-opaque rectangle using Graphics::ScreenQuad
    • Badge widget was moved from Graphics/Extensions and implements item displaying a texture aligned to screen corner.
    • HeadsUpDisplay widget implements visualisation of common graphics application performance parameters like FPS, frame time, resolution, frame buffers count, GPU adapter name, etc. (closed #54)
  • User Interface App implementation was split from Graphics App:
    • Integrates HeadsUpDisplay widget, which can be turned ON by F4 hot-key.
    • HUD and Logo Badge rendering was moved to UserInterface::App
    • Controls and command-line help as well as application runtime parameters are now rendered in Text block panels instead of message box alerts.
    • Base UI App implementation was split to UserInterface/AppBase.h/cpp from template class UserInterface/App.hpp to reduce build overhead.
• Graphics libraries has changed:
  • Graphics Core API changes:
    • Context changes:
      • Context::RequestDeferredAction method was added to request DeferredAction::UploadResources or DeferredAction::CompleteInitialization to be performed when previous frame rendering has completed but next frame rendering was not started yet.
      • Context::GetParallelExecutor provides Taskflow Executor for all parallel execution in the application.
      • Context::GetObjectsRegistry returns instance of Object::Registry which allows to register named Graphics Objects created in scope of current context and request them by name. This allows to reuse single instance of graphics object (like RenderState) for rendering of multiple widgets.
    • CommandQueue changes:
      • Accurate execution state tracking of command lists was implemented using command queue managed thread waiting for GPU execution completion using Fence object. CommandQueue::Execute receives optional argument with lambda callback function called when command list set execution is completed on GPU.
      • CommandQueueDX incapsulates TimestampQueryBuffer instance, which is used internally to query timestamps of command lists execution which are then exposed with Tracy::GpuScope and can be viewed in Tracy Profiler.
      • Different command queue types are supported but not used yet (will be used in future for DirectX copy and compute queues)
    • CommandList changes:
      • CommandList::DebugGroup interface was added to represent named debug group data and effectively reuse its memory in runtime between frames. CMake build option METHANE_COMMAND_DEBUG_GROUPS_ENABLED was added to disable command list debug groups.
      • CommandList::State enum (Pending, Encoding, Committed, Executing) was added and returned with CommandList::GetState
      • CommandList::WaitUntilCompleted method was added
      • CommandList::GetGpuTimeRange method was added which can be called on command list in Pending state. DirectX 12 method implementation has to be enabled with option METHANE_GPU_INSTRUMENTATION_ENABLED, but MacOS implementation works right away.
      • Metal implementations of RenderCommandListMT and BlitCommandListMT was refactored, duplicated code was moved to the base implementation template class CommandListMT.
    • RenderState changes:
      • ViewState was split from RenderState to manage setup of viewports and scissors rects separately from main rendering state.
      • RenderState groups are now compared with memcmp which is slightly improving performance in some cases.
    • RenderCommandList changes:
      • RenderCommandList::SetViewState method was added.
      • RenderCommandList::SetValidationEnabled method was added to disable validation of command list command arguments before encoding to GPU command buffers and increase performance. ParallelRenderCommandList adds the same command to update per-thread command lists option.
    • Resource changes:
      • Resource::SubResource::Count and Resource::SubResource::Index structures were added
      • Resource::SubResource is derived from Data::Chunk and extends with Index and optional BytesRange
      • Resource::GetData method was added returning SubResource at given Index and optional BytesRange, it can be used only for resources with Usage::Readback flag.
      • Resource::GetDataSize method was extended with optional Data::MemoryState argument (Initialized, Reserved values)
      • Resource::GetSubResourceDataSize and Resource::GetSubResourceDataSize methods added by reusing allocated memory between frames.
      • Resource::ReleasePool was removed and replaced with retaining shared pointers to resources in CommandListBase::CommandState kept until execution is completed on GPU. This became possible with accurate execution state tracking of command lists done in CommandQueue waiting thread.
    • Buffer changes:
      • Buffer::StorageMode enum is made a part of buffer settings:
        • Managed - CPU-GPU buffer with automatic data synchronization managed by graphics runtime. Used for volatile buffers.
        • Private - GPU buffer asynchronously uploaded through the intermediate shared CPU-GPU buffer. User by default for vertex, index and constant buffers.
    • Texture changes:
      • All textures are now stored on GPU as private resources and asynchronously updated using upload command list through the CPU-GPU shared resource. All is done inside Texture::SetData method implementation and hidden from API user.
      • Added single-component texture types support like R8Unorm and others.
    • RenderPass changes:
      • Render attachment textures are hold using shared pointers, instead of weak pointers.
      • RenderPass::ReleaseAttachmentTextures method releases all texture shared pointers, which is used on frame resizing in Graphics::App to update existing render pass with new frame buffer textures.
    • ProgramBindings changes:
      • Const-correctness of program argument bindings is checked, i.e. modifications are not allowed when modifier Program::Argument::Modifiers::Constant is specified at construction.
      • Fix performance issue of gradual slowdown in case of repeated program binding updates
    • Eliminated excessive dynamic memory allocations during continuous frames rendering to improve performance by reusing previously allocated memory on previous frames whenever possible (closed #59):
      • CommandListSet interface was added to manage CommandList object collection for memory reuse and effective execution with CommandQueue::Execute
      • BufferSet interface was added to manage Buffer objects collection for memory reuse and effective setup with RenderCommandList::SetVertexBuffers
      • Effective setup of Resource::Barriers was implemented
      • Simplified command list state tracking without use of inheritance and dynamic allocations
      • Minimised sub-resource allocations within MeshBuffers.hpp
    • Events library is used as single notifications mechanism for graphics types:
      • Device is derived Data::IEmitter<IDeviceCallback>
      • Context is derived from Data::IEmitter<IContextCallback>
      • DescriptorHeap is derived fromData::Emitter<IDescriptorHeapCallback> interfainstead of notification
  • Extensions library changes:
    • ScreenQuad changes:
      • Supports rendering without a texture, color filled only.
      • Single instances of RenderState, Sampler, vertex and index Buffer are reused for all screen-quad instances via Object::Registry.
  • Graphics App base implementation changes:
    • Fix animations disabling on startup with command line option
    • Suspend all animations for the time of device resent and window resizing
    • Graphics::App::Render calls WaitForGpu and IsReadyToRender were moved from derived application classes to base implementation.
    • Command line option -e,--emulated-render-pass was added to disable use of DirectX 12 native render passes replaced with emulated behavior, which is useful for frame capturing with many Graphics Debugging & Profiling tools which do not have proper support of DX render passes (closed #62)
  • Graphics Camera changes:
    • Optimized updating view/projection matrices on orientation change, instead of on matrix get
  • Split module Graphics/Helpers to Graphics/Types, Graphics/Primitives and Graphics/Camera
• Platform libraries changes:
  • Platform::App changes:
    • Live window resizing with content update and render on Windows
    • Windows message processing loop was split to smaller functions
    • MacOS application window minimum size is set
    • Handle exceptions and display as alerts
    • Handle keyboard focus to release pressed keys on focus loss (closed #52)
    • Bring window to foreground after startup on MacOS (closed #51)
  • Metal application view AppViewMT implementation was improved to minimise drawables retention time and was instrumented to collect drawable present timings with Tracy::GpuScope. Instrumentation is disabled by default under macro definition TRACY_GPU_PRESENT_INSTRUMENTATION_ENABLED
• Data libraries changes:
  • Events library added (closed #60):
    • Emitter<IEventInterface> template class implements connection to many receivers and emitting functions from IEventInterface to all connected receivers.
    • Receiver<IEventInterface> template class is a base for receivers of IEventInterface. Automatic disconnect on receiver destroying even during event emitted calls is supported.
    • Unit tests and benchmarks implemented for events library.
  • Animations library changes:
    • Animation::DryUpdate method added to call update function with previously updated elapsed duration. AnimationPool::SetDryUpdateOnPauseEnabled calls DryUpdate when animations are paused, which is used for window live resizing with paused animations.
  • Data/Parallel.hpp header with Data::ParallelFor home-brewed implementation was removed and replaced with task flow::for_each implementation from Taskflow library used both in all Methane modules and sample applications.
  • Split Data/Primitives library to Data/Types and Data/Provider libraries
• Instrumentation library changes:
  • Tracy frame profiler is integrated into Methane applications via add_methane_application CMake function and is enabled using build option METHANE_TRACY_PROFILING_ENABLED with collection on demand when METHANE_TRACY_PROFILING_ON_DEMAND is ON, otherwise trace collection from app startup (closed #56)
    • Tracy specific instrumentation was added for frame delimiters, mutex locks, markers and messages
    • Memory allocations instrumentation was added along with call-stacks collection with help of new/delete operators override
    • ScopeTimer was optimised for lower overhead, work without dynamic memory allocations and was extended with Tracy plot instrumentation to display collected timings on Tracy charts.
    • Time zones of command lists execution on GPU are collected with Tracy::GpuContext, Tracy::GpuScope implemented in Methane/TracyGpu.hpp. CommandLists have built in GPU instrumentation enabled with CMake option METHANE_GPU_INSTRUMENTATION_ENABLED
    • Tracy discontinuous frames instrumentation was added for command list debug groups in CommandListBase.cpp due to no support of overlapping regions appearing during parallel rendering in Asteroids sample.
  • ITT instrumentation changes:
    • ITT function and markers arguments metadata collection enabled with build option METHANE_ITT_METADATA_ENABLED via macro definition ITT_ARGUMENTS_METADATA_ENABLED:
      • ITT_FUNCTION_ARG and ITT_MARKER_ARG macroses added in IttApiHelper.h to instrument named arguments of different types.
      • ITT_FUNCTION_TASK macros automatically adds __file__ and __line__ arguments to all instrumented function tasks when ITT metadata is enabled.
    • Methane Kit ITT instrumentation extended:
      • ITT process markers are added as frame delimiters inserted after RenderContext::Preset call and include two metadata arguments: Frame-Buffer-Index and Frame-Index.
      • ITT counter value is added in ScopeTimer instrumentation for displaying collected timings on custom chart in trace
  • META_* instrumentation macro definitions were added in Methane/Instrumentation.h combining both ITT and Tracy instrumentation all together. All ITT_FUNCTION_TASK instrumentation was replaced with META_FUNCTION_TASK all across Methane Kit sources.
    • Logging macros META_LOG is enabled with CMake option METHANE_LOGGING_ENABLED
    • META_SET_THREAD_NAME macros was added to set thread name both using ITT and Tracy APIs and using OS-specific API. Thread names are set automatically for Main thread and for Command Queue threads waiting for command lists execution.
• External libraries:
  • Freetype 2 v2.10.1 library was added
  • Tracy v0.7.1 frame profiler and instrumentation library was added
  • BoostNowide v11.0.0 official library was added to replace obsolete and unsupported fork of NowideStandalone (closed #55)
  • Taskflow v2.6.0 library was added
  • DirectXLibraries submodule was removed and replaced with copy of D3DX12 library files to speedup repository cloning
• Build Infrastructure:
  • Dropped support of Visual Studio 2017 Toolset and switched Windows build to Visual Studio 2019 by default because of missing support of std::wstring_convert<std::codecvt_utf8<char32_t>, char32_t>in VS2017, which is required for UTF8 string conversion to UTF32 encoding in UserInterface/Font.cpp.
  • Build with Clang compiler on Windows is supported. Useful for collecting compilation traces with -ftime-trace which can be analysed either with Chrome Trace viewer or with Compile Score plugin in Visual Studio. Clang build configurations are added in CMakeSettings.json for Visual Studio build convenience.
  • CMake build improvements:
    • Improved build options setup in CMake using MethaneBuildOptions interface target
    • CMake targets linking with PRIVATE & PUBLIC access modifiers
    • Maximum warnings level is used, warnings are treated as errors by default
    • add_methane_embedded_fonts CMake function was added to CMake/MethaneResources.cmake for embeddeding font resources in applications and libraries.
    • GraphViz module dependency diagrams generation enabled using CMake in build scripts Build\Windows\Build.bat and Build\Posix\Build.sh. Diagrams in dot and pngformats are written in build output directory GraphViz (closed #57)
  • Azure Pipelines CI changes:
    • Profiling build configurations were added to build Methane Kit apps and tutorials with maximum ITT & Tracy instrumentation allowing connection with Tracy Profiler app runtime.build uses RelWithDebInfo configuration, so samples and tutorials executables are provided with PDBs in published artifacts.
    • Windows build is switched to Visual Studio 2019.
    • Unit test runs are logged along with exit codes.
• Documentation:
  • High-level architecture diagram was created and published on main ReadMe page (closed #63)
  • Main ReadMe page was fully reorganized to make content shorter and more informative for first time reading. All details were moved to ReadMe pages in nested directories
  • Hello Triangle tutorial was documented in more details
  • Integrated instrumentation was documentated with instructions for trace collection

Per-module shaders, cube textures, sky-box extension, CMake toolchain improvements, platform input infrastructure, full screen support and runtime device reset were made in this release:

• Tutorial updates:
  • Fixed rendering hiccups due to unsynchronised buffer updates (closed #16).
  • ContextController implemented for switching graphics settings in runtime: vsync, device, full-screen and frame buffers count switching supported (closed #30).
• Graphics Core API:
  • Cube Textures are now supported: multiple sub-resource data loading supported on per-Resource level (closed #36).
  • Fixed RenderCommandList multi-reset drawing.
  • Device and System classes allow to enumerate and query available GPU devices and change active device by reseting graphics Context. Switching to full-screen rendering is supported (closed #13).
  • Context frames synchronization was improved in DirectX 12 implementation (closed #32, closed #15).
• Graphics Extensions:
  • SkyBox rendering primitive was added to Graphics Extensions module along with its shaders (closed #38).
  • MeshBuffers extension was created to reduce Tutorials code duplication.
  • ImageLoader supports loading face images to single cube texture.
  • Sphere mesh generator was implemented
• Platform and Data modules:
  • ParallelFor based on std::thread was created.
  • ArcBallCamera was split from ActionCamera implementation for the sake of simplicity.
  • Platform input controllers updated to support triggers by key combinations with modifier keys. Fixed keyboard state after showing Alert/MessageBox.
  • ActionCameraController now supports pivot point change.
  • Application help extended with a list of available GPU devices in system and support for showing command line help.
  • Application user input with keyboard and mouse implemented (closed #3)
  • Action camera supporting rotation, moving and zooming implemented (closed #25)
  • Input controllers infrastructure implemented (closed #26)
  • Animations infrastructure implemented (closed #27)
• Common code cleanup:
  • Removed excessive virtual keywords from method overrides.
  • Concatenated nested namespaces using C++17 standard. Removed using namespaces whenever possible.
  • Changed extensions of Objective-C++ files to .hh/.mm.
  • ITT instrumentation extended to all Methane Kit modules (closed #29)
• Build Infrastructure:
  • Methane CMake modules were improved and split into separate toolchains for Utils, Modules, Resources, Shaders and Applications.
  • Shader and Texture application resources now can be added to dedicated library modules, not just to an application, multiple shader files are now supported. Methane shader object settings changed accordingly and additionally contain shader file name along with function name (closed #37).
  • Build.bat now supports Visual Studio 2019.
  • Test executables are added to install output and are started separately from build to show test results in Azure pipelines.
  • JetBrains ReSharper and CLion IDE configurations with code-style description were set and added.
  • SonarCloud code analysis tool integrated in build scripts.

This release brings Graphics Core API optimizations and refactoring, improved shaders toolchain with HLSL6 & DXC:

• Samples and Tutorials updates:
  • Command line options added to Asteroids sample to modify simulation parameters.
  • Tuned default mesh LODs distribution in Asteroids sample to reduce GPU overhead.
  • Fixed visual shadow offset in ShadowCube tutorial.
  • Rewritten render state settings initialization in a new self-descriptive way.
  • Shaders are now written in HLSL 6 and compiled with new DXC compiler on all platforms (HLSL 5.1 via FXC was used before).
• Graphics Core API improvements and optimizations:
  • Replaced smart pointers syntax from Class::Ptr to Ptr<Class> with template usings also applied to Ptrs, WeakPtr, WeakPtrs, UniquePtr, UniquePtrs, Ref, Refs defined in Memory.hpp.
  • Program Binding improvements and performance optimizations:
    • Moved ProgramBindings interface from Program::ResourceBindings and ProgramBindings::ArgumentBinding from Shader::ResourceBinding. Corresponding API-specific implementations were also split from Program and Shader implementations.
    • ProgramBindings::ArgumentBinding::Settings structure with corresponding GetSettings() method were added, replacing a bunch of virtual getters.
    • Moved ProgramBindings::ArgumentBinding::Modifiers to Program::Argument::Modifiers and added Program::ArgumentDesc structure representing argument with modifiers describing constant and addressable program arguments.
    • Moved CL::SetProramBindings(...) from RenderCommandList to base CommandList interface for future use in compute pipelines.
    • Optimized performance of CommandList::SetProramBindings(...) in DirectX implementation on Windows.
  • Program improvements:
    • Program::InputBufferLayout configuration is simplified by removing of argument names and using semantic names only.
    • Self-descriptive Program initialization with explicit argument modifiers specification implemented within Program::Settings.
  • Command List improvements:
    • BlitCommandList interface was added to provide BLIT operations on GPU memory and is used for UploadCommandList in Context. Public interface is currently empty, but it will be extended in near future. API-specific implementations are used internally (for texture mips generation with Metal).
    • Optimized ParallelRenderCommandList::Reset by resetting per-thread command lists in parallel for DirectX 12 on Windows only.
    • Removed complex command list execution state tracking code from CommandListBase, which was previously used from frames synchronization and became useless now.
    • Moved present command encoding from RenderCommandList::Commit to RenderContext::Present in Metal API implementation on MacOS.
  • Render Context improvements:
    • Context base interface was split from RenderContext interface along with splitting implementation classes. This is a preparation step for adding ComputeContext in future.
    • Fence public interface was added with implementations for DirectX and Metal.
    • RenderContextBase implementation now uses fences as common frames synchronization mechanism between CPU & GPU on all platforms and APIs in platform independent way (replaces dispatch_context_mutex approach on MacOS).
  • Virtual inheritance of API-specific implementation classes from base-implementation classes was eliminated by using template classes like ContextDX<ContextBaseT> and CommandListDX<CommandListBaseT>.
  • Code cleanup: all member fields of base implementation classes are made private with access through class methods only; many typos and naming convention issues were fixed.
• Platform, Data and Common module updates:
  • Graphics::App updates:
    • Added Graphics::AppController and Graphics::IApp abstract interface with Settings, which allows to modify individual settings of graphics app from controller.
    • Restructured Graphics::App::AllSettings to incapsulate Graphics::IApp::Settings, Platform::App::Settings and RenderContext::Settings.
    • Added CLI option and CTRL+Z shortcut to disable all animations in application. Implemented smooth pause of animations.
    • Added CTRL+H shortcut to show/hide HUD in window title.
    • Added F2 shortcut to show command-line help.
  • Mesh.h was split into separate headers with template implementations of specific mesh generators: QuadMesh, CubeMesh, SphereMesh, IcosahedronMesh and UberMesh.
  • Extended ITT instrumentation with Markers for user input events, like key presses and mouse events processed through Platform/Input/ControllersPool.cpp.
  • Methane build version is added to the bottom of application help.
• External libraries:
  • Command line parsing library is replaced with CLI11 to simplify command line parsing code and remove dirty workarounds required by previously used CxxOpts library.
  • Intel ITT instrumentation library is now used from new official repository IttApi instead of old SEAPI repository fork.
  • Updated DirectXTex, DirectXLibraries, STB, CMRC and Catch2 external libraries to their latest versions.
  • Added DirectXCompiler with pre-built binaries of command line tools and libraries for Windows and MacOS.
  • Added RPavlik's CMakeModules.
• Build Infrastructure:
  • Improved shader toolchain by using DirectXShaderCompiler (DXC), replacing FXC compiler on Windows and GLSLang on MacOS, which allows to use HLSL 6 (closed #6).
  • It is not required to start CMake generation from Visual Studio Tools Command Prompt on Windows anymore (removed dependency on VS environment). Removed it from Azure yaml build scripts and from ReadMe. WindowsSDK is found automatically using RPavlik's FindWindowsSDK.cmake.
  • MacOS builder switched from 10.13 to 10.14 due to deprecation notice from Azure Pipelines.

Asteroids sample with multi-threaded rendering and many optimizations was added in this release:

• Asteroids sample demonstrating multi-threaded rendering
  • Many rendering optimizations implemented:
    • Multi-threaded rendering with ParallelRenderCommandList was implemented to reduce CPU frame time.
    • Dynamic asteroid mesh LOD selection implemented with estimation of visible asteroid screen-size. This resolved main GPU performance bottleneck. Visualization of asteroid LODs with coloring as well as dynamic changing LODs distribution are available by hot-keys.
    • 16-bit index buffers are used instead of 32-bit index buffers for all meshes.
    • Asteroids array uniforms buffer update on CPU was significantly accelerated by reducing number of matrix multiplications and using SSE-accelerated implementation of CML matrix multiplication operator.
    • Minimized pixel overdraw with near-to-far rendering order and inverted depth buffer.
    • Minimized texture binding calls with binding whole textures array to program argument at once and selecting asteroid texture with texture index uniform.
  • Application controller added for hot-keys handling:
    • change scene complexity;
    • switch parallel rendering;
    • switch mesh LOD coloring;
    • change mesh LOD complexity;
    • show simulation parameters in message box.
  • Sample is instrumented with scope timers for fast low-overhead profiling.
  • Methane logo badge rendering added.
  • Numerous bug fixes.
• Graphics Core API new features
  • RenderPass on Windows now uses native D3D12 render-pass feature whenever possible (closed #47).
  • ParallelRenderCommandList was added for multi-threaded rendering with an array of internally managed RenderCommandLists into single RenderPass (closed #9).
  • RenderCommandList now can be reset without RenderState setup.
  • RenderState was extended:
    • Depth::write_enabled state was added.
    • Blending state settings were added.
    • Incremental state applying was implemented to eliminate repeated state setup in command list.
  • Program::ResourceBindings improvements:
    • Resources array binding to program arguments is supported.
    • Apply behavior flags added for optimization purposes.
    • Parallel initialization of resource bindings with copying descriptors to GPU.
  • Context improvements:
    • clear_color and clear_depth_stencil settings are now optional (closed #40).
    • Metal frame capture in Xcode is fixed with explicit specification of capture-scope.
    • Getter of content scaling ratio was added (DPI factor on Windows, Retina factor on MacOS).
  • Vulkan API implementation stubs added.
• Graphics Extensions and Helpers new features
  • ScreenQuad graphics extension was added.
  • LogoBadge convenience primitive was added and used for drawing Methane watermark in samples and tutorials (closed #46)
  • Mesh generators now use 16-bit indices instead of 32-bit for lower memory overhead.
  • FpsCounter calculates CPU work percent additionally to frame time (displayed in window header HUD), allowing easily detect CPU/GPU-bound scenario.
• Platform abstraction and Data module features
  • ScopeTimer is implemented for low-overhead profiling.
  • ParallelFor implementation was updated to use Parallel Primitives Library (PPL) on Windows and home-brewed std::async-based implementation on other platforms.
  • Graphics::App rendering is suspended when window is minimized (closed #48).
  • LinuxApp stub implementation added.
• External libraries
  • CML library extended with SSE-accelerated implementation of matrix multiplication operator.
• Build infrastructure
  • Shaders compilation improvements:
    • Metal Shading Language 2.0 is now used instead of 1.0 on MacOS.
    • Fixed HLSL shaders compilation with different macro-definition values in build-time.
    • HLSL shader optimisation compiler flags applied in Release builds.
  • Build scripts were improved:
    • CMake build parameters added to script variables.
    • Build/Posix/Build.sh can be used both on MacOS and Linux.
  • Build version is now correctly added in application files metadata.
  • Linux build is now supported both by Build/Posix/Build.sh script, Visual Studio and Azure Pipelines CI.
  • Gitpod cloud-IDE is now supported:
    • Gitpod configuration added to repository
    • Open in Gitpod button added on ReadMe page.
  • VS Code workspace configuration added.
  • Resharper C++ configuration was added back to repository.
  • Sonar Cube binaries updated to latest version, unfortunately static code analysis is still broken.