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 #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 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 #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 #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.
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
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!
Dkey) demonstrates incremental text mesh updates (can be switched off withU). Typing speed can be changed with=and-keys.HandVkeys.Methane/Samples/AppSettings.hppfor all samples and tutorials. MacOS apps now render with VSync ON, while Windows apps with VSync OFF by default.Apps/Common/Shaders/Primitives.hlsl. As the result this significantly improved rendered image in Asteroids sample (closed #58)Font::Libraryimplements font loading with FreeType 2 libraryFontclass is managingFont::Charglyph metrics, packing to atlas and rendering toR8Unormtexture:Textclass implements rendering of text block with a given font and layout settings:Text::Layoutsettings supported:Text::Wrapdefines wrapping to new line by characters or by woads or no wrapping.Text::HorizonAlignmentwithLeft,RidhtandCenteroptions.Text::VerticalAlignmentwithTop,BottomandCenteroptions.Textis created or updated with non-zerorectinText::Settings.Textis 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.Textitems reuse single instances ofRenderStateandSamplerobjects for allTextwidget instances viaObject::Registry.Unitsenum,UnitPoint,UnitSizeandUnitRectclasses were added inUserInterface/Types.hto handle UI layout positions and sizes in different units (Pixels and Dots) and conversions between them.UserInterface::Contextis a wrapper aroundGraphics::RenderContextand is used for creating all UI items serving both layout and rendering functions.UserInterface::ItemandUserInterface::Containerare base UI classes for all widgets.Panelwidget implements container visualised as semi-opaque rectangle usingGraphics::ScreenQuadBadgewidget was moved fromGraphics/Extensionsand implements item displaying a texture aligned to screen corner.HeadsUpDisplaywidget implements visualisation of common graphics application performance parameters like FPS, frame time, resolution, frame buffers count, GPU adapter name, etc. (closed #54)HeadsUpDisplaywidget, which can be turned ON by F4 hot-key.UserInterface::AppUserInterface/AppBase.h/cppfrom template classUserInterface/Appto improve build time.Contextchanges:Context::RequestDeferredActionmethod was added to requestDeferredAction::UploadResourcesorDeferredAction::CompleteInitializationto be performed when previous frame rendering has completed but next frame rendering was not started yet.Context::GetParallelExecutorprovides Taskflow Executor for all parallel execution in the application.Context::GetObjectsRegistryreturns instance ofObject::Registrywhich 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 (likeRenderState) for rendering of multiple widgets.CommandQueuechanges:Fenceobject.CommandQueue::Executereceives optional argument with lambda callback function called when command list set execution is completed on GPU.CommandQueueDXincapsulatesTimestampQueryBufferinstance, which is used internally to query timestamps of command lists execution which are then exposed withTracy::GpuScopeand can be viewed in Tracy Profiler.CommandListchanges:CommandList::DebugGroupinterface was added to represent named debug group data and effectively reuse its memory in runtime between frames. CMake build optionMETHANE_COMMAND_DEBUG_GROUPS_ENABLEDwas added to disable command list debug groups.CommandList::Stateenum (Pending, Encoding, Committed, Executing) was added and returned withCommandList::GetStateCommandList::WaitUntilCompletedmethod was addedCommandList::GetGpuTimeRangemethod was added which can be called on command list in Pending state. DirectX 12 method implementation has to be enabled with optionMETHANE_GPU_INSTRUMENTATION_ENABLED, butMacOSimplementation works right away.RenderCommandListMTandBlitCommandListMTwas refactored, duplicated code was moved to the base implementation template classCommandListMT.RenderStatechanges:ViewStatewas split fromRenderStateto manage setup of viewports and scissors rects separately from main rendering state.RenderStategroups are now compared withmemcmpwhich is slightly improving performance in some cases.RenderCommandListchanges:RenderCommandList::SetViewStatemethod was added.RenderCommandList::SetValidationEnabledmethod was added to disable validation of command list command arguments before encoding to GPU command buffers and increase performance.ParallelRenderCommandListadds the same command to update per-thread command lists option.Resourcechanges:Resource::SubResource::CountandResource::SubResource::Indexstructures were addedResource::SubResourceis derived fromData::Chunkand extends withIndexand optionalBytesRangeResource::GetDatamethod was added returningSubResourceat givenIndexand optionalBytesRange, it can be used only for resources withUsage::Readbackflag.Resource::GetDataSizemethod was extended with optionalData::MemoryStateargument (Initialized, Reserved values)Resource::GetSubResourceDataSizeandResource::GetSubResourceDataSizemethods added by reusing allocated memory between frames.Resource::ReleasePoolwas removed and replaced with retaining shared pointers to resources inCommandListBase::CommandStatekept until execution is completed on GPU. This became possible with accurate execution state tracking of command lists done inCommandQueuewaiting thread.Bufferchanges:Buffer::StorageModeenum 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.Texturechanges:Texture::SetDatamethod implementation and hidden from API user.R8Unormand others.RenderPasschanges:RenderPass::ReleaseAttachmentTexturesmethod releases all texture shared pointers, which is used on frame resizing inGraphics::Appto update existing render pass with new frame buffer textures.ProgramBindingschanges:Program::Argument::Modifiers::Constantis specified at construction.CommandListSetinterface was added to manageCommandListobject collection for memory reuse and effective execution withCommandQueue::ExecuteBufferSetinterface was added to manageBufferobjects collection for memory reuse and effective setup withRenderCommandList::SetVertexBuffersResource::Barrierswas implementedMeshBuffers.hppEventslibrary is used as single notifications mechanism for graphics types:Deviceis derivedData::IEmitter<IDeviceCallback>Contextis derived fromData::IEmitter<IContextCallback>DescriptorHeapis derived fromData::Emitter<IDescriptorHeapCallback>interfainstead of notificationScreenQuadchanges:RenderState,Sampler, vertex and indexBufferare reused for all screen-quad instances viaObject::Registry.Graphics::App::RendercallsWaitForGpuandIsReadyToRenderwere moved from derived application classes to base implementation.-e,--emulated-render-passwas 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/HelperstoGraphics/Types,Graphics/PrimitivesandGraphics/CameraPlatform::Appchanges:AppViewMTimplementation was improved to minimise drawables retention time and was instrumented to collect drawable present timings withTracy::GpuScope. Instrumentation is disabled by default under macro definitionTRACY_GPU_PRESENT_INSTRUMENTATION_ENABLEDEmitter<IEventInterface>template class implements connection to many receivers and emitting functions fromIEventInterfaceto all connected receivers.Receiver<IEventInterface>template class is a base for receivers ofIEventInterface. Automatic disconnect on receiver destroying even during event emitted calls is supported.Animation::DryUpdatemethod added to call update function with previously updated elapsed duration.AnimationPool::SetDryUpdateOnPauseEnabledcalls DryUpdate when animations are paused, which is used for window live resizing with paused animations.Data/Parallel.hppheader withData::ParallelForhome-brewed implementation was removed and replaced withtask flow::for_eachimplementation from Taskflow library used both in all Methane modules and sample applications.Data/Primitiveslibrary toData/TypesandData/Providerlibrariesadd_methane_applicationCMake function and is enabled using build optionMETHANE_TRACY_PROFILING_ENABLEDwith collection on demand whenMETHANE_TRACY_PROFILING_ON_DEMANDis ON, otherwise trace collection from app startup (closed #56)ScopeTimerwas optimised for lower overhead, work without dynamic memory allocations and was extended with Tracy plot instrumentation to display collected timings on Tracy charts.Tracy::GpuContext,Tracy::GpuScopeimplemented inMethane/TracyGpu.hpp. CommandLists have built in GPU instrumentation enabled with CMake optionMETHANE_GPU_INSTRUMENTATION_ENABLEDCommandListBase.cppdue to no support of overlapping regions appearing during parallel rendering in Asteroids sample.METHANE_ITT_METADATA_ENABLEDvia macro definitionITT_ARGUMENTS_METADATA_ENABLED:ITT_FUNCTION_ARGandITT_MARKER_ARGmacroses added inIttApiHelper.hto instrument named arguments of different types.ITT_FUNCTION_TASKmacros automatically adds__file__and__line__arguments to all instrumented function tasks when ITT metadata is enabled.RenderContext::Presetcall and include two metadata arguments:Frame-Buffer-IndexandFrame-Index.ScopeTimerinstrumentation for displaying collected timings on custom chart in traceMETA_*instrumentation macro definitions were added inMethane/Instrumentation.hcombining both ITT and Tracy instrumentation all together. AllITT_FUNCTION_TASKinstrumentation was replaced withMETA_FUNCTION_TASKall across Methane Kit sources.META_LOGis enabled with CMake optionMETHANE_LOGGING_ENABLEDMETA_SET_THREAD_NAMEmacros 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.std::wstring_convert<std::codecvt_utf8<char32_t>, char32_t>in VS2017, which is required for UTF8 string conversion to UTF32 encoding inUserInterface/Font.cpp.-ftime-tracewhich can be analysed either withChrome Traceviewer or withCompile Scoreplugin in Visual Studio. Clang build configurations are added inCMakeSettings.jsonfor Visual Studio build convenience.MethaneBuildOptionsinterface targetPRIVATE&PUBLICaccess modifiersadd_methane_embedded_fontsCMake function was added toCMake/MethaneResources.cmakefor embeddeding font resources in applications and libraries.Build\Windows\Build.batandBuild\Posix\Build.sh. Diagrams indotandpngformats are written in build output directoryGraphViz(closed #57)RelWithDebInfoconfiguration, so samples and tutorials executables are provided with PDBs in published artifacts.