#pragma region CPL License
/*
Nuclex Native Framework
Copyright (C) 2002-2013 Nuclex Development Labs

This library is free software; you can redistribute it and/or
modify it under the terms of the IBM Common Public License as
published by the IBM Corporation; either version 1.0 of the
License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
IBM Common Public License for more details.

You should have received a copy of the IBM Common Public
License along with this library
*/
#pragma endregion // CPL License

#ifndef NUCLEX_SCENE_GRAPH_ENTITY_H
#define NUCLEX_SCENE_GRAPH_ENTITY_H

#include "Nuclex/Scene/Config.h"
#include "Nuclex/Scene/Graph/ComponentSet.h"
#include "Nuclex/Scene/Graph/ChildEntitySet.h"

namespace Nuclex { namespace Scene { namespace Graph {

  // ------------------------------------------------------------------------------------------- //

  /// <summary>Hierarchical container that houses a number of components</summary>
  /// <remarks>
  ///   <para>
  ///     Entities form a tree and can store components. Components can be anything, from
  ///     primitive data types such as an integer to POD types or objects from a third-party
  ///     library.
  ///   </para>
  ///   <para>
  ///     Typically, entities are used in one of two ways:
  ///   </para>
  ///   <list type="number">
  ///      <item>
  ///        <term>As services:</term>
  ///        <description>
  ///          Here, the entity performs a management task and stores components that
  ///          provide services to other components or interface with the game itself. This
  ///          type of entity does not have a position, but may draw to the screen.
  ///        </description>
  ///      </item>
  ///      <item>
  ///        <term>As scene nodes:</term>
  ///        <description>
  ///          If used as a scene node, the entity has a transformation (position,
  ///          orientation and scale) and is used to build a hierarchical scene: there might
  ///          be a <tt>Car</tt> entity that has four child <tt>Wheel</tt> entities, with
  ///          the children's transformation typically being relative to their parent.
  ///        </description>
  ///      </item>
  ///   </list>
  ///   <para>
  ///     <example>Example use case of an entity</example>
  ///     <code>
  ///       std::shared_ptr<Entity> bicycle = std::make_shared<Entity>();
  ///       bicycle->Components.Add(std::make_unique<Matrix44>());
  ///
  ///       bicycle->Children.Add(std::make_shared<Entity>());
  ///       bicycle->Children.Add(std::make_shared<Entity>());
  ///
  ///       for(std::shared_ptr<Entity> wheel : bicycle->Children) {
  ///         wheel->Components.Add(std::make_unique<Matrix44>());
  ///       }
  ///     </code>
  ///   </para>
  /// </remarks>
  class Entity : public std::enable_shared_from_this<Entity> {
    friend ChildEntitySet;

    /// <summary>Components carried by the entity</summary>
    public: ComponentSet Components;

    /// <summary>The entity's children</summary>
    public: ChildEntitySet Children;

    /// <summary>Initializes a new entity</summary>
    public: NUCLEX_SCENE_API Entity() : Children(*this) {}

    /// <summary>Retrieves the parent of this entity, if any</summary>
    /// <returns>The parent of this entity, if it has a parent</returns>
    public: NUCLEX_SCENE_API Entity *GetParent() {
      return this->parent;
    }

    /// <summary>Retrieves the parent of this entity, if any</summary>
    /// <returns>The parent of this entity, if it has a parent</returns>
    public: NUCLEX_SCENE_API const Entity *GetParent() const {
      return this->parent;
    }

    /// <summary>Assigns the parent of this entity or clears it</summary>
    /// <param name="parent">Parent that will be assigned to the entity</param>
    /// <returns>The parent of this entity, if it has a parent</returns>
    protected: NUCLEX_SCENE_API void SetParent(Entity *parent) {
      this->parent = parent;
    }

    /// <summary>Registers a component that is a permanent part of the entity</summary>
    /// <typeparam name="TComponent">Type of component that will be registered</typeparam>
    /// <param name="component">Component that will be registered</param>
    /// <remarks>
    ///   <para>
    ///     While a component/entity system is data driven, sometimes you have a type of
    ///     entities that have to contain certain elements. A bone in a bone-animated
    ///     mesh for example would always have a position, orientation and scale. And sometimes,
    ///     you just want to reduce the number of allocations needed or allow an entity to
    ///     be pooled, like shots from a weapon.
    ///   </para>
    ///   <para>
    ///     Built-in components allow you to create special entity types that include some
    ///     components with them as direct members.
    ///   </para>
    /// </remarks>
    protected: template<typename TComponent> void RegisterBuiltInComponent(
      TComponent *component
    ) {
      this->Components.Add(
        typeid(TComponent),
        component,
        [](void *component) { delete static_cast<TComponent *>(component); }
      );
    }

    /// <summary>Points to the parent entity of this entity</summary>
    /// <remarks>
    ///   Not a shared_ptr because that would keep the parent alive indefinitely
    ///   (circular relationship) and not a weak_ptr because the parent may be used
    ///   inline and not have a shared_ptr pointing to it.
    /// </remarks>
    private: Entity *parent;

  };

  // ------------------------------------------------------------------------------------------- //

}}} // namespace Nuclex::Scene::Graph

#endif // NUCLEX_SCENE_GRAPH_ENTITY_H