210 lines
7.1 KiB
C
210 lines
7.1 KiB
C
#pragma once
|
|
|
|
/// \file blueprint.h
|
|
/// \author Folling <mail@folling.io>
|
|
|
|
#include <ikarus/errors.h>
|
|
#include <ikarus/macros.h>
|
|
#include <ikarus/stdtypes.h>
|
|
|
|
/// \defgroup blueprints Blueprints
|
|
/// \brief Blueprints are templates for entities.
|
|
/// @{
|
|
|
|
IKARUS_BEGIN_HEADER
|
|
|
|
/// \brief Templates for sharing common properties between entities.
|
|
/// \details A blueprint allows sharing properties between entities.
|
|
/// Each entity the blueprint is linked to will have a corresponding value for
|
|
/// each of the blueprint's properties. Changes in blueprints will be reflected
|
|
/// in all linked entities.
|
|
struct IkarusBlueprint;
|
|
|
|
/// \brief Flags for creating a blueprint.
|
|
enum IkarusBlueprintCreateFlags {
|
|
/// \brief No flags.
|
|
IkarusBlueprintCreateFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Creates a new blueprint.
|
|
/// \param project The project to create the blueprint in.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The name of the blueprint.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must not be empty.
|
|
/// \param flags Flags for creating the blueprint.
|
|
/// \return The created blueprint or null if an error occurs.
|
|
/// \param error_out \see errors.h
|
|
/// \remark Ownership remains with libikarus.
|
|
IKA_API IkarusBlueprint * ikarus_blueprint_create(
|
|
struct IkarusProject * project,
|
|
char const * name,
|
|
IkarusBlueprintCreateFlags flags,
|
|
struct IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for creating a blueprint from an entity.
|
|
enum IkarusBlueprintCreateFromEntityFlags {
|
|
/// \brief No flags.
|
|
IkarusBlueprintCreateFromEntityFlags_None = 0,
|
|
/// \brief The default values of the properties will be set to the values of the source entity.
|
|
IkarusBlueprintCreateFromEntityFlags_AdoptDefaultValues = 1 << 0,
|
|
/// \brief The entity will be linked to the blueprint, and all values will be turned into properties.
|
|
IkarusBlueprintCreateFromEntityFlags_LinkEntity = 1 << 1,
|
|
};
|
|
|
|
/// \brief Creates a new blueprint from an entity.
|
|
/// \details Each value of the entity will be copied into the blueprint as a property.
|
|
/// \param entity The entity to create the blueprint from.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The name of the blueprint.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must not be empty.
|
|
/// \param flags Flags for creating the blueprint.
|
|
/// \param error_out \see errors.h
|
|
/// \return The created blueprint or null if an error occurs.
|
|
IKA_API IkarusBlueprint * ikarus_blueprint_create_from_entity(
|
|
struct IkarusEntity * entity,
|
|
char const * name,
|
|
IkarusBlueprintCreateFromEntityFlags flags,
|
|
struct IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for copying a blueprint.
|
|
enum IkarusBlueprintCopyFlags {
|
|
/// \brief No flags.
|
|
IkarusBlueprintCopyFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Copies a blueprint.
|
|
/// \param blueprint The blueprint to copy.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param flags Flags for copying the blueprint.
|
|
/// \param error_out \see errors.h
|
|
/// \return The copied blueprint or null if an error occurs.
|
|
IKA_API struct IkarusBlueprint * ikarus_blueprint_copy(
|
|
struct IkarusBlueprint * blueprint,
|
|
IkarusBlueprintCopyFlags flags,
|
|
struct IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for deleting a blueprint.
|
|
enum IkarusBlueprintDeleteFlags {
|
|
/// \brief No flags.
|
|
IkarusBlueprintDeleteFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Deletes a blueprint, all associated properties, and their values.
|
|
/// \param blueprint The blueprint to delete.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param flags Flags for deleting the blueprint.
|
|
/// \remark Must not be used after deletion.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_blueprint_delete(
|
|
struct IkarusBlueprint * blueprint,
|
|
IkarusBlueprintDeleteFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the project a blueprint belongs to.
|
|
/// \param blueprint The blueprint to get the project of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The project the blueprint belongs to.
|
|
/// \remark Ownership remains with libikarus.
|
|
IKA_API struct IkarusProject * ikarus_blueprint_get_project(
|
|
struct IkarusBlueprint * blueprint,
|
|
struct IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the name of a blueprint.
|
|
/// \param blueprint The blueprint to get the name of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The name of the blueprint.
|
|
/// \remark Ownership remains with libikarus.
|
|
IKA_API char const * ikarus_blueprint_get_name(
|
|
struct IkarusBlueprint * blueprint,
|
|
struct IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for setting the name of a blueprint.
|
|
enum IkarusBlueprintSetNameFlags {
|
|
/// \brief No flags.
|
|
IkarusBlueprintSetNameFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Sets the name of a blueprint.
|
|
/// \param blueprint The blueprint to set the name of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The new name of the blueprint.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must not be empty.
|
|
/// \param flags Flags for setting the name of the blueprint.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_blueprint_set_name(
|
|
struct IkarusBlueprint * blueprint,
|
|
char const * name,
|
|
IkarusBlueprintSetNameFlags flags,
|
|
struct IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the properties of a blueprint.
|
|
/// \param blueprint The blueprint to get the properties of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param size_out An out parameter for the number of items in the returned array or undefined if an error occurs.
|
|
/// \param error_out \see errors.h
|
|
/// \return The properties of the blueprint or null if an error occurs.
|
|
IKA_API struct IkarusProperty ** ikarus_blueprint_get_properties(
|
|
struct IkarusBlueprint * blueprint,
|
|
size_t * size_out,
|
|
struct IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the number of properties of a blueprint.
|
|
/// \param blueprint The blueprint to get the properties count of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The number of properties of the blueprint or 0 if an error occurs.
|
|
IKA_API size_t ikarus_blueprint_get_properties_count(
|
|
struct IkarusBlueprint * blueprint,
|
|
struct IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets all entities linked to a blueprint.
|
|
/// \param blueprint The blueprint to get the entities of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param size_out An out parameter for the number of items in the returned array or undefined if an error occurs.
|
|
/// \remark Ignore if null.
|
|
/// \param error_out \see errors.h
|
|
/// \return The entities linked to the blueprint or null if an error occurs.
|
|
IKA_API struct IkarusEntity ** ikarus_blueprint_get_entities(
|
|
struct IkarusBlueprint * blueprint,
|
|
size_t * size_out,
|
|
struct IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the number of entities linked to a blueprint.
|
|
/// \param blueprint The blueprint to get the entities count of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The number of entities linked to the blueprint or 0 if an error occurs.
|
|
IKA_API size_t ikarus_blueprint_get_entities_count(
|
|
struct IkarusBlueprint * blueprint,
|
|
struct IkarusErrorData * error_out
|
|
);
|
|
|
|
IKARUS_END_HEADER
|
|
|
|
/// @}
|