Skip to content

basic-usage.md

Latest commit

 

History

History
104 lines (82 loc) · 5.1 KB

basic-usage.md

File metadata and controls

104 lines (82 loc) · 5.1 KB
Raw

Basic usage

Use C++20, include headers under Nikerva/, and link a Nikerva CMake target. Public C++ types live in namespace Nikerva. You do not need to define or import namespace Engine in a standalone application.

After setup, use the full manual to look up every widget and property. Set, apply, and change explains the difference between constructor options, live setters, bindings, and declarations.

Add the library to a host

This CMake fragment assumes the checkout is at external/Nikerva and your application already has a MyApp target. Configure GLM through your normal package manager or CMAKE_PREFIX_PATH.

set(NIKERVA_BUILD_VULKAN OFF CACHE BOOL "" FORCE)
set(NIKERVA_BUILD_SAMPLE OFF CACHE BOOL "" FORCE)
set(NIKERVA_BUILD_TESTS OFF CACHE BOOL "" FORCE)
add_subdirectory(external/Nikerva)
target_compile_features(MyApp PRIVATE cxx_std_20)
target_link_libraries(MyApp PRIVATE Nikerva::Core)

Core gives you controls and drawing descriptions. A visible native application also needs a window, event loop, fonts/images, and a renderer. Enable NIKERVA_BUILD_VULKAN and link Nikerva::Vulkan to use the supplied backend. The shared sample host and the three small applications show that integration. Their window, Vulkan resources, and input translation stay outside the UI library.

For another graphics API, implement the Renderer2D and TextRenderer interfaces for the builder, or consume UIPaintSnapshot for retained UI. Implementing the builder interfaces alone does not render retained snapshots.

Build and check Core independently

From the Nikreon repository root, with GLM discoverable:

cmake -S external/Nikerva -B build-nikerva-core -DNIKERVA_BUILD_VULKAN=OFF -DNIKERVA_BUILD_SAMPLE=ON -DNIKERVA_BUILD_TESTS=ON
cmake --build build-nikerva-core --config Debug
ctest --test-dir build-nikerva-core -C Debug --output-on-failure

For a single-configuration generator such as Ninja, also set -DCMAKE_BUILD_TYPE=Debug on the configure command. For vcpkg, pass its toolchain file and your installed package directory. Core itself links only GLM; the library's default vcpkg manifest also lists dependencies for the optional backend and graphical samples.

The graphical targets are NikervaRetainedExample, NikervaDeclarativeExample, and NikervaSideBySideExample. They require both Vulkan and sample builds to be enabled. Core-only builds run the non-graphics tests without creating sample executables. See examples for launch commands and screenshots.

Option Default Purpose
NIKERVA_BUILD_VULKAN ON Build shaders and Vulkan renderers
NIKERVA_BUILD_SAMPLE ON Build the three small graphical examples
NIKERVA_BUILD_TESTS ON Register library CTest checks
NIKERVA_ENABLE_DIAGNOSTICS OFF Enable builder/backend instrumentation in Debug or RelWithDebInfo

Release and MinSizeRel disable that optional instrumentation. Retained paint snapshots and the retained diagnostic APIs remain available in all configurations. The Nikreon root forwards NIKREON_EDITOR_UI_DIAGNOSTICS to the library option.

Choose an approach

Use retained mode for long-lived forms, large collections, and screens whose structure changes infrequently. It lets an unchanged screen reuse its existing UI work.

Use every-frame declarations for compact tools and screens that are convenient to express directly from current state. Keep the builder alive and use stable IDs even though declarations run again each frame.

Migration to the new name

The checkout is now external/Nikerva. Retained includes use Nikerva/UI/Retained/..., declarative includes use Nikerva/UI/Decl/..., and renderer includes use Nikerva/Renderer/...; classes formerly declared in the shared engine namespace now use Nikerva::. Update forward declarations as well as includes. CMake targets, cache options, sample executables use the new name. Shared geometry and renderer statistics stay directly under Nikerva/UI; declarative layout helpers and builder statistics live under Nikerva/UI/Decl. There are no old namespace, include, or target aliases.

Start with a clean build directory. Old CMake caches contain absolute paths and old target names. The root override for an external library checkout is now NIKERVA_SOURCE_DIR.

Nikerva remains a Git submodule, hosted at Nikcher256/Nikerva. Commit and push library changes first, then record and push that revision in the parent repository so a fresh clone can fetch the referenced library commit. For an existing Nikreon checkout, run git submodule sync --recursive after pulling the updated .gitmodules to refresh its locally cached remote URL. The rename itself does not change scene, project, asset, or workspace formats.

Historical benchmark captures keep their original schema identifier and content. The old benchmark executable and previous samples are no longer in this checkout; the three examples above are the current runnable demonstrations.