src/ascension/scene_node.h

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 * Copyright 2025 Mike Becker. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *   1. Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *
 *   2. Redistributions in binary form must reproduce the above copyright
 *      notice, this list of conditions and the following disclaimer in the
 *      documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef ASCENSION_SCENE_NODE_H
#define ASCENSION_SCENE_NODE_H

#include <cx/list.h>
#include <cx/string.h>

#include "datatypes.h"
#include "transform.h"

typedef struct asc_scene_node_s AscSceneNode;

typedef void(*asc_scene_node_destroy_func)(AscSceneNode*);
typedef void(*asc_scene_node_update_func)(AscSceneNode*);

enum AscRenderGroup {
    ASC_RENDER_GROUP_NONE = -1,
    ASC_RENDER_GROUP_SPRITE_OPAQUE,
    ASC_RENDER_GROUP_SPRITE_BLEND,
    ASC_RENDER_GROUP_COUNT
};

struct asc_scene_node_s {
    AscSceneNode *parent;
    AscSceneNode *prev;
    AscSceneNode *next;
    AscSceneNode *children;
    AscSceneNode *last_child;
    cxmutstr name;
    /**
     * List of AscBehavior structs.
     * Not a pointer list!
     */
    CxList *behaviors;
    asc_scene_node_destroy_func destroy_func;
    asc_scene_node_update_func update_func;
    asc_vec3f position;
    asc_vec3f rotation;
    asc_vec3f scale;
    asc_transform transform;
    asc_transform world_transform;
    enum AscRenderGroup render_group;
    /**
     * Custom flags for this node.
     * The #ASC_SCENE_NODE_FLAGS_MASK bits are reserved for general flags.
     */
    uint32_t flags;
};


/**
 * The reserved bits for general flags.
 */
#define ASC_SCENE_NODE_FLAGS_MASK             0xFF000000
/**
 * Set when a graphics update is needed in this frame.
 */
#define ASC_SCENE_NODE_UPDATE_GRAPHICS        0x01000000
/**
 * Set when a graphics updated happened last frame.
 */
#define ASC_SCENE_NODE_GRAPHICS_UPDATED       0x02000000
/**
 * Set when a transform update is needed in this frame.
 */
#define ASC_SCENE_NODE_UPDATE_TRANSFORM       0x04000000
/**
 * Set when a transform update happened last frame.
 */
#define ASC_SCENE_NODE_TRANSFORM_UPDATED      0x08000000
/**
 * Set when the node's transform is directly manipulated via matrix operations.
 * When this flag is set, position/rotation/scale values won't be used to
 * calculate the transform matrix.
 */
#define ASC_SCENE_NODE_CUSTOM_TRANSFORM       0x10000000
/**
 * Set when the node is not supposed to be shown on screen.
 */
#define ASC_SCENE_BEHAVIOR_PAUSED             0x40000000
/**
 * Set when the node is not supposed to be shown on screen.
 */
#define ASC_SCENE_NODE_HIDDEN                 0x80000000


/**
 * Creates an empty node that may serve as a container for other nodes.
 *
 * The free_func of this node will be a simple free().
 *
 * @return the new node
 */
AscSceneNode *asc_scene_node_empty(void);

// TODO: create a common init-function that all "subclasses" use, which also debug-logs the assigned name

/**
 * Unlinks the node from its parent and frees the entire subtree.
 *
 * The free_func of this node and all child nodes is called, starting
 * with the leaf nodes and terminating with \p node.
 *
 * @param node the node to unlink
 */
void asc_scene_node_free(AscSceneNode *node);

/**
 * Sets the name of a node.
 *
 * @param node the node
 * @param name the new name of the node
 */
void asc_scene_node_name(AscSceneNode *node, const char *name);

/**
 * Returns the name of the node.
 *
 * Names are not necessarily unique.
 *
 * @param node the node
 * @return the node's name or a calculated name if it does not have one
 */
cxstring asc_scene_node_get_name(AscSceneNode *node);

/**
 * Links a node to a (new) parent.
 *
 * @param parent the (new) parent
 * @param node the node to link
 */
void asc_scene_node_link(
        AscSceneNode *restrict parent,
        AscSceneNode *restrict node
);

/**
 * Unlinks a node from its parent.
 *
 * This might be useful to temporarily remove a subtree from a scene.
 * To permanently remove the node use asc_scene_node_free().
 *
 * @param node the node to unlink
 */
void asc_scene_node_unlink(AscSceneNode *node);

void asc_node_update(AscSceneNode *node);

void asc_node_update_transform(AscSceneNode *node);


/**
 * This is the z-position a simple 2D element should have to allow
 * stacking 2D elements with depth-test.
 */
#define ASC_SCENE_2D_DEPTH_OFFSET 0.0078125f

ASC_TRANFORM_FUNC void asc_set_position(AscSceneNode *node, float x, float y, float z) {
    node->position.x = x;
    node->position.y = y;
    node->position.z = z;
    asc_clear_flag(node->flags, ASC_SCENE_NODE_CUSTOM_TRANSFORM);
    asc_node_update_transform(node);
}

ASC_TRANFORM_FUNC void asc_set_position2d(AscSceneNode *node, int x, int y) {
    node->position.x = (float)x;
    node->position.y = (float)y;
    asc_clear_flag(node->flags, ASC_SCENE_NODE_CUSTOM_TRANSFORM);
    asc_node_update_transform(node);
}

ASC_TRANFORM_FUNC asc_vec2i asc_get_position2d(AscSceneNode *node) {
    return asc_vec2i_new(node->position.x, node->position.y);
}

ASC_TRANFORM_FUNC void asc_set_rotation(AscSceneNode *node, float x, float y, float z) {
    node->rotation.x = x;
    node->rotation.y = y;
    node->rotation.z = z;
    asc_clear_flag(node->flags, ASC_SCENE_NODE_CUSTOM_TRANSFORM);
    asc_node_update_transform(node);
}

ASC_TRANFORM_FUNC void asc_set_scale(AscSceneNode *node, float width, float height, float depth) {
    node->scale.width = width;
    node->scale.height = height;
    node->scale.depth = depth;
    asc_clear_flag(node->flags, ASC_SCENE_NODE_CUSTOM_TRANSFORM);
    asc_node_update_transform(node);
}


/**
 * Directly modifies the transformation matrix by multiplying it with another matrix.
 * This will set the node to use the custom transform mode.
 *
 * @param node the node to modify
 * @param matrix the matrix to multiply with the current transform
 */
ASC_TRANFORM_FUNC void asc_transform_multiply(AscSceneNode *node, const asc_transform matrix) {
    asc_set_flag(node->flags, ASC_SCENE_NODE_CUSTOM_TRANSFORM);
    asc_mat4f_mulst(node->transform, node->transform, matrix);
    asc_node_update_transform(node);
}

/**
 * Directly sets the transformation matrix.
 * This will set the node to use the custom transform mode.
 *
 * @param node the node to modify
 * @param matrix the matrix to set as the transform
 */
ASC_TRANFORM_FUNC void asc_transform_set_matrix(AscSceneNode *node, const asc_transform matrix) {
    asc_set_flag(node->flags, ASC_SCENE_NODE_CUSTOM_TRANSFORM);
    memcpy(node->transform, matrix, sizeof(asc_transform));
    asc_node_update_transform(node);
}

/**
 * Resets the node to use component-based transformation.
 * This will recalculate the transform matrix from position, rotation, and scale.
 *
 * @param node the node to modify
 */
ASC_TRANFORM_FUNC void asc_transform_reset_to_components(AscSceneNode *node) {
    asc_clear_flag(node->flags, ASC_SCENE_NODE_CUSTOM_TRANSFORM);
    asc_node_update_transform(node);
}


#endif