Methane Kit v0.4
egorodet
released this
10 Sep 14:59
·
1692 commits
to master
since this 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 withU
). 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
andV
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)
- App settings configuration is moved to
- Typography tutorial was added to demonstrate new Methane Font rendering & Text layout widget:
- 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 libraryFont
class is managingFont::Char
glyph metrics, packing to atlas and rendering toR8Unorm
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
withLeft
,Ridht
andCenter
options.Text::VerticalAlignment
withTop
,Bottom
andCenter
options.- Note: layout settings are applicable only when
Text
is created or updated with non-zerorect
inText::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 ofRenderState
andSampler
objects for allText
widget instances viaObject::Registry
.
- User Interface Types library added with common UI types:
Units
enum,UnitPoint
,UnitSize
andUnitRect
classes were added inUserInterface/Types.h
to handle UI layout positions and sizes in different units (Pixels and Dots) and conversions between them.UserInterface::Context
is a wrapper aroundGraphics::RenderContext
and is used for creating all UI items serving both layout and rendering functions.UserInterface::Item
andUserInterface::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 usingGraphics::ScreenQuad
Badge
widget was moved fromGraphics/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 byF4
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 classUserInterface/App.hpp
to reduce build overhead.
- Integrates
- Typography library implements fonts management and text blocks rendering classes (closed #4):
- Graphics libraries has changed:
- Graphics Core API changes:
Context
changes:Context::RequestDeferredAction
method was added to requestDeferredAction::UploadResources
orDeferredAction::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 ofObject::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 (likeRenderState
) 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
incapsulatesTimestampQueryBuffer
instance, which is used internally to query timestamps of command lists execution which are then exposed withTracy::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)
- Accurate execution state tracking of command lists was implemented using command queue managed thread waiting for GPU execution completion using
CommandList
changes:CommandList::DebugGroup
interface was added to represent named debug group data and effectively reuse its memory in runtime between frames. CMake build optionMETHANE_COMMAND_DEBUG_GROUPS_ENABLED
was added to disable command list debug groups.CommandList::State
enum (Pending, Encoding, Committed, Executing) was added and returned withCommandList::GetState
CommandList::WaitUntilCompleted
method was addedCommandList::GetGpuTimeRange
method 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
, butMacOS
implementation works right away.- Metal implementations of
RenderCommandListMT
andBlitCommandListMT
was refactored, duplicated code was moved to the base implementation template classCommandListMT
.
RenderState
changes:ViewState
was split fromRenderState
to manage setup of viewports and scissors rects separately from main rendering state.RenderState
groups are now compared withmemcmp
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
andResource::SubResource::Index
structures were addedResource::SubResource
is derived fromData::Chunk
and extends withIndex
and optionalBytesRange
Resource::GetData
method was added returningSubResource
at givenIndex
and optionalBytesRange
, it can be used only for resources withUsage::Readback
flag.Resource::GetDataSize
method was extended with optionalData::MemoryState
argument (Initialized, Reserved values)Resource::GetSubResourceDataSize
andResource::GetSubResourceDataSize
methods added
by reusing allocated memory between frames.Resource::ReleasePool
was removed and replaced with retaining shared pointers to resources inCommandListBase::CommandState
kept until execution is completed on GPU. This became possible with accurate execution state tracking of command lists done inCommandQueue
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.
- 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
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 inGraphics::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
- Const-correctness of program argument bindings is checked, i.e. modifications are not allowed when modifier
- 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 manageCommandList
object collection for memory reuse and effective execution withCommandQueue::Execute
BufferSet
interface was added to manageBuffer
objects collection for memory reuse and effective setup withRenderCommandList::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 derivedData::IEmitter<IDeviceCallback>
Context
is derived fromData::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 indexBuffer
are reused for all screen-quad instances viaObject::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
callsWaitForGpu
andIsReadyToRender
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
toGraphics/Types
,Graphics/Primitives
andGraphics/Camera
- Graphics Core API changes:
- 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 withTracy::GpuScope
. Instrumentation is disabled by default under macro definitionTRACY_GPU_PRESENT_INSTRUMENTATION_ENABLED
- Data libraries changes:
- Events library added (closed #60):
Emitter<IEventInterface>
template class implements connection to many receivers and emitting functions fromIEventInterface
to 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.- 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 withData::ParallelFor
home-brewed implementation was removed and replaced withtask flow::for_each
implementation from Taskflow library used both in all Methane modules and sample applications.- Split
Data/Primitives
library toData/Types
andData/Provider
libraries
- Events library added (closed #60):
- Instrumentation library changes:
- Tracy frame profiler is integrated into Methane applications via
add_methane_application
CMake function and is enabled using build optionMETHANE_TRACY_PROFILING_ENABLED
with collection on demand whenMETHANE_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 inMethane/TracyGpu.hpp
. CommandLists have built in GPU instrumentation enabled with CMake optionMETHANE_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 definitionITT_ARGUMENTS_METADATA_ENABLED
:ITT_FUNCTION_ARG
andITT_MARKER_ARG
macroses added inIttApiHelper.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
andFrame-Index
. - ITT counter value is added in
ScopeTimer
instrumentation for displaying collected timings on custom chart in trace
- ITT process markers are added as frame delimiters inserted after
- ITT function and markers arguments metadata collection enabled with build option
META_*
instrumentation macro definitions were added inMethane/Instrumentation.h
combining both ITT and Tracy instrumentation all together. AllITT_FUNCTION_TASK
instrumentation was replaced withMETA_FUNCTION_TASK
all across Methane Kit sources.- Logging macros
META_LOG
is enabled with CMake optionMETHANE_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.
- Logging macros
- Tracy frame profiler is integrated into Methane applications via
- 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 inUserInterface/Font.cpp
. - Build with Clang compiler on Windows is supported. Useful for collecting compilation traces with
-ftime-trace
which can be analysed either withChrome Trace
viewer or withCompile Score
plugin in Visual Studio. Clang build configurations are added inCMakeSettings.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 toCMake/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
andBuild\Posix\Build.sh
. Diagrams indot
andpng
formats are written in build output directoryGraphViz
(closed #57)
- Improved build options setup in CMake using
- 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.
- 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
- Dropped support of Visual Studio 2017 Toolset and switched Windows build to Visual Studio 2019 by default because of missing support of
- 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