nw/gfx/gfx_SceneBuilder.h

/*---------------------------------------------------------------------------*
  Project:  NintendoWare
  File:     gfx_SceneBuilder.h

  Copyright (C)2009-2010 Nintendo Co., Ltd./HAL Laboratory, Inc.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

  $Revision: $
 *---------------------------------------------------------------------------*/


#ifndef NW_GFX_SCENEBUILDER_H_
#define NW_GFX_SCENEBUILDER_H_

#include <nw/gfx/gfx_SceneObject.h>

namespace nw
{
namespace gfx
{

class SceneNode;

//---------------------------------------------------------------------------
//! @brief        シーン上のオブジェクトを生成するクラスです。
//---------------------------------------------------------------------------
class SceneBuilder
{
private:
    NW_DISALLOW_COPY_AND_ASSIGN(SceneBuilder);

public:
    //! コンストラクタです。
    SceneBuilder()
    : m_IsFixedSizeMemory(true),
      m_MaxChildren(SceneObject::DEFAULT_MAX_CHILDREN),
      m_MaxCallbacks(SceneObject::DEFAULT_MAX_CALLBACKS),
      m_BufferOption(0),
      m_SharedMaterialModel(NULL),
      m_MaxAnimObjectsPerGroup(1),
      m_ParticleSetMarginCount(0),
      m_IsAnimationEnabled(true)
    {}

    //! デストラクタです。
    ~SceneBuilder() {}

    //! リソースを設定します。
    SceneBuilder& Resource(ResSceneObject resource) { m_Resource = resource; return *this; }

    //! @brief 生成時以外にもメモリを確保するかどうかのフラグを設定します。
    //!
    //!        true を指定すると、生成時のみ固定サイズのメモリ確保を行います。
    //!
    //!        false を指定すると、生成時以外にも必要に応じて動的にメモリ確保が行われます。
    SceneBuilder& IsFixedSizeMemory(bool isFixedSizeMemory)
    {
        m_IsFixedSizeMemory = isFixedSizeMemory;
        return *this;
    }

    //! 子の最大数を設定します。
    SceneBuilder& MaxChildren(int maxChildren) { m_MaxChildren = maxChildren; return *this; }

    //! 管理できるコールバックの最大数を設定します。
    SceneBuilder& MaxCallbacks(int maxCallbacks) { m_MaxCallbacks = maxCallbacks; return *this; }

    //! @brief バッファの生成オプションを設定します。
    //!
    //!
    //! @param bufferOption Model::BufferOptionで定義されるフラグの組み合わせです。
    //!        SharedMaterialModel が指定された場合、BufferOption は指定することができません。
    //!        BufferOption が指定された場合は動作を停止します。
    //!
    //! @param[in] bufferOption Model::BufferOptionで定義されるフラグの組み合わせです。
    //!
    SceneBuilder& BufferOption(bit32 bufferOption) { m_BufferOption = bufferOption; return *this; }

    //! @brief マテリアルを共有する場合に共有元のモデルを設定します。
    //!
    //!        所有権の移動を行いません。
    //!        マテリアルを最初に生成したモデルがマテリアルの所有権を持ちます。
    //!        共有元のモデルが先に破棄された場合は未定義の動作となります。
    //!
    //! @param[in] model 共有するマテリアルを持つモデルです。
    //!
    SceneBuilder& SharedMaterialModel(Model* model) { m_SharedMaterialModel = model; return *this; }

    //! @brief アニメオブジェクトの最大数を指定します。
    //!
    //! @details 複数のAnimGroupを持つ場合は、
    //!          各AnimGroupごとのアニメオブジェクトの最大数のうち、最も大きいものを指定してください。
    //!
    SceneBuilder& MaxAnimObjectsPerGroup(s32 maxAnimObjects) { m_MaxAnimObjectsPerGroup = maxAnimObjects; return *this; }

    //! @brief パーティクルセットを生成する場合のバッファを生成する数を設定します。
    //!
    //!        値が指定されている場合、リソース内パーティクルセット数に指定された値を加えた数で生成されます。
    //!        ０が指定されている場合、リソース内パーティクルセット数にデフォルトマージンを加えた数で生成されます。
    //!
    SceneBuilder& ParticleSetMarginCount(int marginCount) { m_ParticleSetMarginCount = marginCount; return *this; }

    //! @brief アニメーション可能かを設定します。
    //!
    //!        false を指定すると AnimBinding の生成を行いません。
    //!        そのためアニメーションのバインドができなくなりますが、
    //!        アニメーション更新の処理が行われなくなるため、
    //!        シーンアップデートのパフォーマンスが向上します。
    SceneBuilder& IsAnimationEnabled(bool isAnimationEnabled) { m_IsAnimationEnabled = isAnimationEnabled; return *this; }

    //! @brief        設定されたリソースから、ひとつのシーンオブジェクトを生成します。
    //!               このとき、リソースに含まれる子階層以下のオブジェクトは生成されませんので、
    //!               個別に生成する必要があります。
    //!
    //! @param[in]    allocator アロケータです。
    //! @param[in]    deviceAllocator デバイスメモリのアロケータです。
    //!
    //! @return       生成したシーンオブジェクトを返します。
    //!
    SceneObject* CreateObject(os::IAllocator* allocator, os::IAllocator* deviceAllocator);

    //! @brief        設定されたリソースをルートノードとしたシーンツリーを生成します。
    //!               リソースに含まれる子階層以下の参照をたどってすべてインスタンス化していくため、
    //!               リソースファイルに含まれるモデルすべてを初期化する、などの処理で使用すると
    //!               子階層のオブジェクトが2重にインスタンス化されます。
    //!
    //! @param[in]    allocator アロケータです。
    //! @param[in]    deviceAllocator デバイスメモリのアロケータです。
    //!
    //! @return       生成したルートノードのシーンオブジェクトを返します。
    //!
    SceneObject* CreateTree(os::IAllocator* allocator, os::IAllocator* deviceAllocator);

    //! @brief        生成時に必要なメモリサイズを取得します。
    //!
    //! CreateObject() を呼び出すときに必要なメモリサイズを返します。
    //!
    //! メモリサイズは SceneBuilder の設定によって変化します。
    //! すべての設定が終わった後にこの関数を呼び出してください。
    //!
    //! @param[in]    alignment メモリのアライメントです。
    size_t GetMemorySize(
        size_t alignment = os::IAllocator::DEFAULT_ALIGNMENT
    ) const
    {
        os::MemorySizeCalculator size(alignment);

        BuildSceneObject(&size, NULL, NULL, m_Resource, NULL, NULL, false, true);

        return size.GetSizeWithPadding(alignment);
    }

    //! @brief        生成時に必要なデバイスメモリサイズを取得します。
    //!
    //! CreateObject() を呼び出すときに必要なデバイスメモリサイズを返します。
    //!
    //! メモリサイズは SceneBuilder の設定によって変化します。
    //! すべての設定が終わった後にこの関数を呼び出してください。
    //!
    //! @param[in] alignment 計算に用いるアライメントです。2 のべき乗である必要があります。
    size_t GetDeviceMemorySize(
        size_t alignment = os::IAllocator::DEFAULT_ALIGNMENT
    ) const
    {
        os::MemorySizeCalculator size(alignment);

        BuildSceneObject(NULL, &size, NULL, m_Resource, NULL, NULL, false, true);

        return size.GetSizeWithPadding(alignment);
    }

    //! @brief        シーンツリー生成時に必要なメモリサイズを取得します。
    //!
    //! CreateTree() を呼び出すときに必要なメモリサイズを返します。
    //!
    //! メモリサイズは SceneBuilder の設定によって変化します。
    //! すべての設定が終わった後にこの関数を呼び出してください。
    //!
    //! @param[in] alignment 計算に用いるアライメントです。2 のべき乗である必要があります。
    size_t GetMemorySizeTree(
        size_t alignment = os::IAllocator::DEFAULT_ALIGNMENT
    ) const
    {
        os::MemorySizeCalculator size(alignment);

        BuildSceneObject(&size, NULL, NULL, m_Resource, NULL, NULL, true, true);

        return size.GetSizeWithPadding(alignment);
    }

    //! @brief        シーンツリー生成時に必要なデバイスメモリサイズを取得します。
    //!
    //! CreateTree() を呼び出すときに必要なメモリサイズを返します。
    //!
    //! メモリサイズは SceneBuilder の設定によって変化します。
    //! すべての設定が終わった後にこの関数を呼び出してください。
    //!
    //! @param[in]    alignment メモリのアライメントです。
    size_t GetDeviceMemorySizeTree(
        size_t alignment = os::IAllocator::DEFAULT_ALIGNMENT
    ) const
    {
        os::MemorySizeCalculator size(alignment);

        BuildSceneObject(NULL, &size, NULL, m_Resource, NULL, NULL, true, true);

        return size.GetSizeWithPadding(alignment);
    }

private:
    //----------------------------------------
    //! @name シーンオブジェクトの生成
    //@{

    //! @brief        シーンオブジェクトを生成します。
    //!
    //! isCalculation を true にすると生成に必要なメモリサイズを求め、
    //! オブジェクトの生成を行ないません。
    //!
    //! @param        pSize メモリサイズを求めるための MemorySizeCalculator へのポインタです。
    //! @param        pDeviceSize デバイスメモリサイズを求めるための MemorySizeCalculator へのポインタです。
    //! @param[in]    parent 親となるSceneNodeです。
    //! @param[in]    resource リソースです。
    //! @param[in]    allocator アロケータです。
    //! @param[in]    deviceAllocator デバイスメモリのアロケータです。
    //! @param[in]    isRecursive 再帰的に子階層を生成するかどうかのフラグです。
    //! @param[in]    isCalculation メモリサイズを計算するかどうかのフラグです。
    //!
    //! @return       生成したオブジェクトを返します。
    //!
    SceneObject* BuildSceneObject(
        os::MemorySizeCalculator* pSize,
        os::MemorySizeCalculator* pDeviceSize,
        SceneNode* parent,
        ResSceneObject resource,
        os::IAllocator* allocator,
        os::IAllocator* deviceAllocator,
        bool isRecursive,
        bool isCalculation) const;

    //! @brief        ノードの子を構築します。
    //!
    //! isCalculation を true にすると生成に必要なメモリサイズを求め、
    //! オブジェクトの生成を行ないません。
    //!
    //! @param        pSize メモリサイズを求めるための MemorySizeCalculator へのポインタです。
    //! @param        pDeviceSize デバイスメモリサイズを求めるための MemorySizeCalculator へのポインタです。
    //! @param[in]    parent 親のシーンノードです。
    //! @param[in]    resource リソースです。
    //! @param[in]    allocator アロケータです。
    //! @param[in]    deviceAllocator デバイスメモリのアロケータです。
    //! @param[in]    isCalculation メモリサイズを計算するかどうかのフラグです。
    //!
    void BuildChildren(
        os::MemorySizeCalculator* pSize,
        os::MemorySizeCalculator* pDeviceSize,
        SceneNode* parent,
        ResSceneObject resource,
        os::IAllocator* allocator,
        os::IAllocator* deviceAllocator,
        bool isCalculation) const;

    //@}

    ResSceneObject m_Resource;
    bool m_IsFixedSizeMemory;
    int m_MaxChildren;
    int m_MaxCallbacks;
    bit32 m_BufferOption;
    Model* m_SharedMaterialModel;

    int m_MaxAnimObjectsPerGroup;
    int m_ParticleSetMarginCount;

    bool m_IsAnimationEnabled;
};

} // namespace gfx
} // namespace nw

#endif // NW_GFX_SCENEBUILDER_H_