Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

4.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    UIBindings.hpp
 * @brief   The UI entry points the SDK drives: the Yoga layout pass, hit testing,
 *          draw order, and the computed-box queries.
 * @details These were defined inline in WebSDKEntry.cpp, which made them
 *          web-only by accident of where they sat — the implementations use
 *          nothing but `activeCtx()` and the registry. Declared here (like
 *          RendererBindings), they are registered with embind by WebSDKEntry on
 *          the web and wrapped for QuickJS by the EHT-generated native bindings,
 *          from THIS file's declarations. One implementation, two registrations.
 */
#pragma once

#include <unordered_map>
#include "../core/Types.hpp"

namespace esengine {

namespace ecs {
    class Registry;
}

/** Solve the UI layout tree against the world-space box UI lives in — its size
 *  is the available area, its center is where screen roots are placed.
 *  `propertyDirty` is the SDK's O(1) "an authored UINode/FlexContainer field
 *  changed" signal. */
void uiLayout_update(ecs::Registry& registry, f32 boxLeft, f32 boxBottom, f32 boxRight, f32 boxTop,
                     bool propertyDirty);

/** The runtime raycast. The pointer is a RAY — a screen point names one, and
 *  only a chosen plane turns it into a position — so content away from z = 0
 *  (a mesh, a sprite on another layer) can be hit at all. `pick`/`pickAll`
 *  below stay a point: the editor asks about the flat design surface. */
void uiHitTest_update(ecs::Registry& registry,
                      f32 originX, f32 originY, f32 originZ,
                      f32 dirX, f32 dirY, f32 dirZ);
/**
 * @brief The hit test with a ray per domain — world content and world-space UI
 *        answer the first, screen UI the second.
 *
 * @details A separate entry point rather than more parameters: these are bound by
 *          NAME, and widening a signature makes an older core throw rather than
 *          decline.
 */
void uiHitTest_updateDomains(ecs::Registry& registry,
                             f32 worldOriginX, f32 worldOriginY, f32 worldOriginZ,
                             f32 worldDirX, f32 worldDirY, f32 worldDirZ,
                             f32 screenOriginX, f32 screenOriginY, f32 screenOriginZ,
                             f32 screenDirX, f32 screenDirY, f32 screenDirZ);
u32 uiHitTest_getHitEntity();
u32 uiHitTest_pick(ecs::Registry& registry, f32 worldX, f32 worldY);
u32 uiHitTest_pickAll(ecs::Registry& registry, f32 worldX, f32 worldY);
u32 uiHitTest_pickResult(u32 index);

/** Resolved (Yoga-pass) pixel size of a UI node, for the editor's selection
 *  outline. The node's world box is this size, pivot-centered on its Transform. */
f32 uiNode_computedWidth(ecs::Registry& registry, u32 entity);
f32 uiNode_computedHeight(ecs::Registry& registry, u32 entity);

void uiRenderOrder_update(ecs::Registry& registry);
/** The layers of what the Canvases hold with no uiOrder of its own, by entity id. */
const std::unordered_map<u32, i32>* uiTreeLayers();

/** An entity's UI draw order, so the SDF text path can interleave glyph quads
 *  with UI quads. -1 = not a UI node. */
i32 ui_getRenderOrder(ecs::Registry& registry, u32 entity);
/** Mask bit of the owning Canvas' layer, for Camera.cullingMask. 0 = not a UI node. */
u32 ui_getCullBit(ecs::Registry& registry, u32 entity);
/**
 * @brief Whether @p entity belongs to the SCREEN rather than to the world.
 *
 * @details The same answer the renderer partitions its collects by, asked here
 *          because the SDK submits some of the screen's geometry itself — glyph
 *          quads — into the list the panel behind them went into.
 */
bool ui_isScreenDomain(ecs::Registry& registry, u32 entity);


/** UINode computed state that is not embind-readable off the component. */
bool getUINodeHiddenInTree(ecs::Registry& registry, u32 entity);
/** Subtree opacity resolved by the layout pass (UINode.opacity multiplied down). */
f32 getUINodeAlphaInTree(ecs::Registry& registry, u32 entity);
f32 getUINodeComputedWidth(ecs::Registry& registry, u32 entity);
f32 getUINodeComputedHeight(ecs::Registry& registry, u32 entity);

/** Compose world transforms now (the UI layout pass reads them). */
void transform_update(ecs::Registry& registry);

/** Copy a drawable entity's complete world matrix to 16 caller-owned floats.
 *  False for missing or collapsed geometry; leaves the output unchanged. */
bool transform_copyFlatRenderMatrix(ecs::Registry& registry, u32 entity, uintptr_t outputPtr);

}  // namespace esengine