hdk grid api - hollow foundation library

This library provides the foundation for hdk, including core data structures, utilities, and interfaces that other components of the grid will build upon. It serves as the backbone of the system, enabling efficient management of holographic data and interactions.

Shared Struct Wrapper

The SharedPtrWrapper class is a reference-counted wrapper for shared pointers to structures. It provides a mechanism to manage the lifetime of shared resources while allowing for efficient access and caching of shared pointers. The wrapper ensures that shared pointers are properly managed and that resources are released when no longer needed, preventing memory leaks and ensuring efficient memory usage.

The SharedPtrWrapper instances should be able to be used interchangeably with the underlying raw pointers in other C API calls, while still benefiting from the reference counting and caching mechanisms provided by the wrapper.

Primitive Wrapper

The PrimitiveWrapper class is a template wrapper for primitive types that provides a consistent interface for getting and setting properties. It allows for easy access to the underlying primitive value while also providing a layer of abstraction that can be useful for managing state and interactions within the grid system. The wrapper can be used to encapsulate primitive values and provide additional functionality, such as validation or transformation, while still allowing for direct access to the underlying value when needed.

Event Publishing System (EPS)

hdk::grid::eps::Conduit<Args...> is a thread-safe, type-safe event dispatcher. Attach callbacks with Attach(...); each subscription returns a move-only Tap handle. Fire the event with Trigger(...) or operator(). Callbacks run in attachment order from a snapshot taken under lock, so dispatch happens outside the lock and is safe against callbacks that detach or pause other taps.

Tap supports IsActive(), Detach(), Pause(), Resume(), and IsPaused(). A tap becomes inactive after it is detached or if the underlying conduit is gone.

hdk::grid::eps::TapScope groups multiple taps for bulk management. Add taps with Add(...) or operator<<, pause/resume them together with PauseAll() and ResumeAll(), and disconnect everything with DetachAll(). Its destructor also calls DetachAll(), so any taps still owned by the scope are disconnected automatically. Clear() only forgets the stored taps; the subscriptions stay active until detached elsewhere or the scope is destroyed.

Example usage of hdk::grid::eps::Conduit and Tap:

hdk::grid::eps::Conduit<int> changed;
auto tap = changed.Attach([](int value) { /* handle value */ });
changed.Trigger(42);
tap.Detach();

Example usage of hdk::grid::eps::TapScope to manage multiple groups of taps:

1. Somewhere else in the code base there are some conduits:
2. Your class that needs to subscribe to some of these:
3. Notice that we'vee got two TapScope instances, you can have as many as you want.
4. Since the TapScope instances are members of MyClass, they will automatically detach all their taps when an instance of MyClass is destroyed, ensuring that there are no dangling subscriptions and that resources are properly cleaned up.

// #1
struct EventData { /* ... */ };
hdk::grid::eps::Conduit<EventData*> event;
hdk::grid::eps::Conduit<int> changed;
hdk::grid::eps::Conduit<void> onMinimized, onRestored, onRender;
 
// #2
class MyClass {
  protected:
  // #3
  hdk::grid::eps::TapScope genTaps, stateTaps;
  public:
  MyClass() {
    // So let's say you normally do some things a lot of the time...
    stateTaps << changed.Attach([this](int value) { /* handle value */ });
    stateTaps << event.Attach([](EventData* data) { /* handle event */ });
    stateTaps << onRender.Attach([]() { /* do render stuff */ });
    // But sometimes you want to pause that stuff, but not everything else.
    genTaps << onMinimized.Attach([this]() { stateTaps.PauseAll(); });
    genTaps << onRestored.Attach([this]() { stateTaps.ResumeAll(); });
    // Notice the genTaps group is always active and those handlers are used to control the other stateTaps group.
  }
}; // # 4

Shared HDK Packaging Notes

hdk-grid currently has no examples, but it follows the same install-prefix conventions as the rest of HDK.

Under a common install prefix:

• headers install to ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}
• package metadata installs under ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/cmake/hdk-grid

Other HDK modules that provide examples install shared assets to assets under the same prefix by default, so all HDK outputs remain co-located.