nw/gfx/gfx_AnimEvaluator.h

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

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

  These coded instructions, statements, and computer programs contain proprietary
  information of Nintendo and/or its licensed developers and are protected by
  national and international copyright laws. 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.

  The content herein is highly confidential and should be handled accordingly.

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

#ifndef NW_GFX_ANIMEVALUATOR_H_
#define NW_GFX_ANIMEVALUATOR_H_

#include <nw/gfx/gfx_BaseAnimEvaluator.h>
#include <nw/gfx/gfx_SharedAnimCache.h>
#include <nw/ut/ut_MoveArray.h>
#include <nw/ut/ut_RuntimeTypeInfo.h>

namespace nw {
namespace gfx {

//---------------------------------------------------------------------------
//! @brief 汎用アニメーションを評価するクラスです。
//!
//! アニメーションデータを保持し、ファンクションカーブの評価を行います。
//---------------------------------------------------------------------------
class AnimEvaluator : public BaseAnimEvaluator
{
public:
    NW_UT_RUNTIME_TYPEINFO;

    //----------------------------------------
    //! @name 作成
    //@{

    //! 汎用アニメーション評価を構築するクラスです。
    class Builder
    {
    public:
        //! コンストラクタです。
        Builder()
        : m_AnimData(NULL),
          m_MaxMembers(64),
          m_MaxAnimMembers(64),
          m_AllocCache(false) {}

        //! アニメーションデータを設定します。
        Builder& AnimData(const nw::anim::ResAnim& animData) { m_AnimData = animData; return *this; }

        //! @brief アニメーション対象メンバの最大数を設定します。
        //!
        //! AnimEvaluator::Bind に渡す AnimGroup の AnimGroup::GetMemberCount の値を設定してください。
        //! 複数の AnimGroup に Bind する場合は、最大値を設定してください。
        Builder& MaxMembers(int maxMembers)
        {
            NW_ASSERT(maxMembers > 0);
            m_MaxMembers = maxMembers;
            return *this;
        }

        //! @brief 実際にアニメーションするメンバの最大数を設定します。
        //!
        //! AnimData() に渡す anim::res::ResAnim の anim::res::ResAnim::GetMemberAnimSetCount の値を設定してください。
        //! AnimEvaluator::ChangeAnim で複数の ResAnim を切り替える場合は、最大値を設定してください。
        Builder& MaxAnimMembers(int maxAnimMembers)
        {
            NW_ASSERT(maxAnimMembers > 0);
            m_MaxAnimMembers = maxAnimMembers;
            return *this;
        }

        //! キャッシュバッファを確保してキャッシュを有効にするかどうかを設定します。
        Builder& AllocCache(bool allocCache) { m_AllocCache = allocCache; return *this; }

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

            GetMemorySizeInternal(&size);

            return size.GetSizeWithPadding(alignment);
        }

        //! @details :private
        void GetMemorySizeInternal(os::MemorySizeCalculator* pSize) const
        {
            os::MemorySizeCalculator& size = *pSize;

            size += sizeof(AnimEvaluator);
            AnimEvaluator::GetMemorySizeForInitialize(pSize, m_AnimData, m_MaxMembers, m_MaxAnimMembers, m_AllocCache);
        }

        //! @brief 汎用アニメーション評価を生成します。
        //!
        //! @param[in] allocator アロケータです。
        //!
        //! @return 生成された汎用アニメーション評価です。
        //!
        AnimEvaluator* Create(os::IAllocator* allocator)
        {
            void* buf = allocator->Alloc(sizeof(AnimEvaluator));

            if (buf == NULL)
            {
                return NULL;
            }

            AnimEvaluator* animEvaluator = new(buf) AnimEvaluator(allocator);

            Result result = animEvaluator->Initialize(m_AnimData, m_MaxMembers, m_MaxAnimMembers, m_AllocCache);
            NW_ASSERT(result.IsSuccess());

            return animEvaluator;
        }

    private:
        nw::anim::ResAnim m_AnimData;
        int m_MaxMembers;
        int m_MaxAnimMembers;
        bool m_AllocCache;
    };

    //@}

    //----------------------------------------
    //! @name 基本操作
    //@{

    //! @brief アニメーションを変更します。
    //!
    //! GetCacheBufferSizeNeeded() の値が変化しますので、
    //! SetCacheBuffer() や SetSharedCacheBuffer() を使用している場合はバッファの再設定が必要です。
    //!
    //! 内部で確保したキャッシュバッファは、自動的にサイズ変更されます。
    //!
    //! @param animData アニメーションデータです。
    //! @sa BaseAnimEvaluator::ChangeAnim
    virtual void ChangeAnim(const nw::anim::ResAnim animData)
    {
        // キャッシュサイズを求めるのにm_AnimDataを参照するので、
        // 先に更新する必要がある
        BaseAnimEvaluator::ChangeAnim(animData);

        m_CachePtrs.Resize(animData.GetMemberAnimSetCount());

        if (!m_IsCacheExternal && m_CacheBuf != NULL)
        {
            os::SafeFree(m_CacheBuf, &GetAllocator());

            // サイズ0でのAllocを回避する
            // CreateEmpty～Anim()などを使用した場合に起こりうる
            if (animData.GetMemberAnimSetCount() != 0)
            {
                m_CacheBuf = GetAllocator().Alloc(GetCacheBufferSizeNeeded());
                NW_NULL_ASSERT(m_CacheBuf);

                SetCacheBufferPointers();
            }
        }
    }

    //! @brief マテリアル名を置き換えてアニメーションを関連付けます。
    //!
    //! マテリアルアニメーションのバインド先を
    //! 名前が materialName であるマテリアルに置き換えてバインドします。
    //!
    //! マテリアルアニメーション以外では使用できません。
    //!
    //! materialName の文字数が長すぎるとバインドに失敗することがあります。
    //!
    //! @param[in] animGroup アニメーショングループです。
    //! @param[in] materialName バインドするマテリアル名です。文字数の制限があります。
    //!
    //! @return バインドの結果を返します。
    //!
    //! @sa TryBind
    Result ForceBindMaterialAnim(AnimGroup* animGroup, const char* materialName);

    //@}

    //----------------------------------------
    //! @name 評価
    //@{

    //! @brief メンバ単位でアニメーション結果を取得します。
    //!
    //! @param[out] target アニメーション結果を書き込む対象です。
    //! @param[in] memberIdx メンバインデックスです。
    //!
    //! @return アニメーション結果を返します。
    //! ブレンドオペレーションを使用する場合は、返り値のアニメーション結果を使用してください。
    //!
    virtual const anim::AnimResult* GetResult(
        void* target,
        int memberIdx) const;

    //@}

    //----------------------------------------
    //! @name 取得／設定
    //@{

    //! @brief メンバに関連付けられたアニメーションが存在するかどうかを取得します。
    //!
    //! @param[in] memberIdx メンバインデックスです。
    //!
    //! @return アニメーションが存在すれば true を返します。
    //!
    virtual bool HasMemberAnim(int memberIdx) const
    {
        NW_MINMAXLT_ASSERT(memberIdx, 0, m_BindIndexTable.Size());
        return m_BindIndexTable[memberIdx] != NotFoundIndex;
    }

    //@}

    //----------------------------------------
    //! @name キャッシュ
    //@{

    //! アニメーション評価結果の内部キャッシュが古ければ更新します。
    virtual void UpdateCache() { this->UpdateCacheNonVirtual(); }

    //! :private
    void UpdateCacheNonVirtual();

    //! :private
    void UpdateCacheImpl();

    //! キャッシュバッファに必要なサイズ（バイト数）を取得します。
    //! @return 必要なサイズ（バイト数）です。
    virtual int GetCacheBufferSizeNeeded() const;

    //! キャッシュバッファを取得します。
    virtual const void* GetCacheBuffer() const { return m_CacheBuf; }

    //! @brief キャッシュバッファを設定します。
    //! この関数で指定したキャッシュバッファはデストラクタで解放されません。
    //!
    //! @param[in] buf キャッシュバッファ用のメモリの先頭アドレスです。
    //! NULL の場合、キャッシュが無効になります。
    //! @param[in] size キャッシュバッファのサイズ（バイト数）です。
    //!
    virtual void SetCacheBuffer(void* buf, int size)
    {
        m_CacheBuf = buf;
        if (buf != NULL)
        {
            NW_ASSERT(size >= GetCacheBufferSizeNeeded());
            (void)size;
            m_IsCacheDirty = true;
            m_IsCacheExternal = true;
            SetCacheBufferPointers();
        }
    }

    //! @brief 他のAnimEvaluatorと共有可能なキャッシュを使用するように設定します。
    void SetSharedCacheBuffer(SharedAnimCache* cache)
    {
        // 他の形式のキャッシュが指定されているならアサートで止める
        NW_ASSERT(m_CacheBuf == NULL);
        NW_ASSERT(!m_IsCacheExternal);

        m_SharedCache = cache;
        if (cache != NULL)
        {
            m_IsCacheDirty = true;
            m_IsCacheExternal = true;
            m_UseSharedCache = true;
            m_CacheBuf = cache->GetCacheBuffer();
            SetCacheBufferPointers();
        }
        else
        {
            m_CacheBuf = NULL;
        }
    }

    //@}

protected:
    //----------------------------------------
    //! @name コンストラクタ／デストラクタ
    //@{

    //! コンストラクタです。
    //!
    //! :private
    AnimEvaluator(
        os::IAllocator* allocator);

    //! デストラクタです。
    //!
    //! :private
    virtual ~AnimEvaluator()
    {
        if (!m_IsCacheExternal && m_CacheBuf != NULL)
        {
            GetAllocator().Free(m_CacheBuf);
        }
    }

    //@}

    //! Initialize() の実行に必要なメモリサイズを取得します。
    //!
    //! :private
    static void GetMemorySizeForInitialize(
        os::MemorySizeCalculator* pSize,
        const nw::anim::ResAnim& animData,
        const int maxMembers,
        const int maxAnimMembers,
        bool allocCache);

    //! @details :private
    Result Initialize(
        const nw::anim::ResAnim& animData,
        const int maxMembers,
        const int maxAnimMembers,
        bool allocCache);

    //! キャッシュバッファに必要なサイズ（バイト数）を取得します。
    //!
    //! :private
    static int GetCacheBufferSizeNeeded(const anim::ResAnim& animData);

    //! 各メンバアニメのキャッシュバッファへのポインタを設定します。
    //!
    //! :private
    void SetCacheBufferPointers();

    //! AnimResult を実サイズで詰めたバッファ
    //!
    //! :private
    void* m_CacheBuf;

    //! 共有するキャッシュのポインタ
    SharedAnimCache* m_SharedCache;

    //! 各メンバアニメの m_CacheBuf 中のポインタ
    //!
    //! :private
    ut::MoveArray<anim::AnimResult*> m_CachePtrs;

private:
    //! マテリアル名を置き換えてメンバインデックスを引く関数オブジェクトです。
    //!
    //! :private
    class ReplaceMaterialNameIndexGetterFunctor
    {
    private:
        static const int MAX_BUFFER_LENGTH = 256;

    public:
        ReplaceMaterialNameIndexGetterFunctor(const char* materialName)
            : m_MaterialName(materialName),
              m_LenMaterialName(0)
        {
            NW_NULL_ASSERT(materialName);
            m_LenMaterialName = std::strlen(m_MaterialName);
        }

        int operator() (AnimGroup* animGroup, anim::ResMemberAnim member)
        {
            const char MATERIAL_PREFIX[] = "Materials[\"";
            const size_t MATERIAL_PREFIX_LEN = sizeof(MATERIAL_PREFIX) - 1;

            const char* path = member.GetPath();
            size_t lenPath = std::strlen(path);

            NW_ASSERTMSG(std::strncmp(path, MATERIAL_PREFIX, MATERIAL_PREFIX_LEN) == 0, "Not material animation member.");

            NW_FAILSAFE_IF (lenPath <= MATERIAL_PREFIX_LEN)
            {
                // 書き換え対象のパスの長さが異常なので
                // リソースが壊れている可能性がある。

                // -1 は辞書引きで見つからない場合の戻り値
                return -1;
            }

            // "Materials[\"" は確定しているので、その次の文字列までポインタを進める。
            path += MATERIAL_PREFIX_LEN;
            lenPath -=  MATERIAL_PREFIX_LEN;

            // 次の " を探す。
            while ((*path != 0) && (*path != '\"'))
            {
                ++path;
                --lenPath;
            }

            // この時点で path は '\"' からはじまるか、NULL 終端を指している。

            NW_FAILSAFE_IF (MATERIAL_PREFIX_LEN + m_LenMaterialName + lenPath + 1 > MAX_BUFFER_LENGTH)
            {
                // 書き換えたパスがバッファに収まらない。

                // -1 は辞書引きで見つからない場合の戻り値
                return -1;
            }

            // パスを作成する。
            char replacedPath[MAX_BUFFER_LENGTH];
            ut::strncpy(replacedPath, MAX_BUFFER_LENGTH, MATERIAL_PREFIX, MATERIAL_PREFIX_LEN);
            ut::strncat(replacedPath, MAX_BUFFER_LENGTH, m_MaterialName, m_LenMaterialName);
            ut::strncat(replacedPath, MAX_BUFFER_LENGTH, path, lenPath);

            return animGroup->GetResAnimGroupMemberIndex(replacedPath);
        }

    private:
        const char* m_MaterialName;
        size_t m_LenMaterialName;
    };
};

} // namespace gfx
} // namespace nw

#endif // NW_GFX_ANIMEVALUATOR_H_