Version 0.4: Font rendering & Text layout, User Interface basis, Tracy Profiler & GPU instrumentation, Memory and Performance optimizations

[egorodet]

Methane Kit v0.4 Release

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 in Asteroids sample (closed Add SRGB gamma correction in samples #58)
• User Interface libraries were added (closed User interface library #5):
  • Typography library implements fonts management and text blocks rendering classes (closed Cross-platform text rendering #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 type:
    • 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 Render Context Heads Up Display (HUD) #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 to improve build time.
• 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 Reduce number of dynamic memory allocations during frames rendering #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 Add command line argument to graphics apps to replace DX12 native render pass with emulation #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 Keyboard shortcuts stop working after switching to full screen window on MacOS #52)
    • Bring window to foreground after startup on MacOS (closed MacOS window appears in background after application startup #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 Events interface connection between classes #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 Add instrumentation for Tracy realtime profiler #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 Use boost::nowide from official repository #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 Support Cmake modules dependency diagrams generation with GraphViz #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 Create high-level architecture diagram #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