gfx/res/gfx_ResTexture.h

/*---------------------------------------------------------------------------*
  Project:  NintendoWare
  File:     gfx_ResTexture.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: 18106 $
 *---------------------------------------------------------------------------*/

#ifndef NW_GFX_RESTEXTURE_H_
#define NW_GFX_RESTEXTURE_H_

#include <GLES2/gl2.h>
#include <GLES2/gl2ext.h>

#include <nw/ut/ut_Color.h>
#include <nw/ut/ut_ResUtil.h>
#include <nw/ut/ut_ResDictionary.h>
#include <nw/gfx/res/gfx_ResSceneObject.h>
#include <nw/gfx/res/gfx_ResRevision.h>
#include <nw/gfx/res/gfx_ResTypeInfo.h>

namespace nw
{
namespace os
{
class IAllocator;
} // namesapce os

namespace gfx {
namespace res {

class ResGraphicsFile;

//! @details :private
struct ResTextureData : public ResSceneObjectData
{
};

//! @details :private
struct ResPixelBasedTextureData : public ResTextureData
{
    nw::ut::ResS32 m_Height;
    nw::ut::ResS32 m_Width;
    nw::ut::ResU32 m_Format;
    nw::ut::ResU32 m_FormatType;
    nw::ut::ResS32 m_MipmapSize;
    nw::ut::ResU32 m_TextureObject;
    nw::ut::ResU32 m_LocationFlag;
    nw::ut::ResU32 m_FormatHW;
};

//! @details :private
struct ResPixelBasedImageData
{
    enum
    {
        AREA_NO_MALLOC = 0,
        AREA_FCRAM = NN_GX_MEM_FCRAM,
        AREA_VRAMA = NN_GX_MEM_VRAMA,
        AREA_VRAMB = NN_GX_MEM_VRAMB
    };

    nw::ut::ResS32      m_Height;
    nw::ut::ResS32      m_Width;
    nw::ut::ResS32      m_ImageDataTableCount;
    nw::ut::Offset      toImageDataTable;
    nw::os::IAllocator* m_DynamicAllocator;
    u32                 m_BitsPerPixel;
    u32                 m_LocationAddress;
    u32                 m_MemoryArea;
};

//! @details :private
struct ResImageTextureData : public ResPixelBasedTextureData
{
    nw::ut::Offset toImage;
};

//! @details :private
struct ResCubeTextureData : public ResPixelBasedTextureData
{
    enum { MAX_CUBE_FACE = 6 };

    union
    {
        struct
        {
            nw::ut::Offset toPositiveXImage;
            nw::ut::Offset toNegativeXImage;
            nw::ut::Offset toPositiveYImage;
            nw::ut::Offset toNegativeYImage;
            nw::ut::Offset toPositiveZImage;
            nw::ut::Offset toNegativeZImage;
        };

        nw::ut::Offset toImagesTables[ MAX_CUBE_FACE ];
    };
};

//! @details :private
struct ResShadowTextureData : public ResPixelBasedTextureData
{
    nw::ut::Offset toImage;
    nw::ut::ResBool m_IsPerspectiveShadow;
    nw::ut::ResF32 m_ShadowZBias;
    nw::ut::ResF32 m_ShadowZScale;
};

//! @details :private
struct ResReferenceTextureData : public ResTextureData
{
    nw::ut::BinString toPath;
    nw::ut::Offset toTargetTexture;
};

//--------------------------------------------------------------------------
//! @brief テクスチャを表すバイナリリソースの基底クラスです。
//---------------------------------------------------------------------------
class ResTexture : public ResSceneObject
{
public:
    enum { TYPE_INFO = NW_GFX_RES_TYPE_INFO(ResTexture) };
    enum { SIGNATURE = NW_RES_SIGNATURE32('TXOB') };
    enum { BINARY_REVISION = REVISION_RES_TEXTURE };

    NW_RES_CTOR_INHERIT( ResTexture, ResSceneObject )

    //---------------------------------------------------------------------------
    //! @brief        リビジョンを取得します。
    //!
    //! @return       リソースのリビジョン情報です。
    //---------------------------------------------------------------------------
    u32 GetRevision() const { return this->GetHeader().revision; }

    //---------------------------------------------------------------------------
    //! @brief        参照ではない実体のテクスチャを取得します。
    //!
    //! @return       参照テクスチャの場合には参照先を返します。
    //!               それ以外の場合には自身のインスタンスを返します。
    //---------------------------------------------------------------------------
    NW_INLINE ResTexture        Dereference();
    NW_INLINE const ResTexture  Dereference() const;

    //---------------------------------------------------------------------------
    //! @brief        テクスチャリソースを初期化します。
    //!
    //! @return       Setup の結果を返します。
    //---------------------------------------------------------------------------
    Result Setup(os::IAllocator* allocator, ResGraphicsFile graphicsFile);

    //---------------------------------------------------------------------------
    //! @brief        リソースの後始末をおこないます。
    //---------------------------------------------------------------------------
    void    Cleanup();
};

typedef nw::ut::ResArrayPatricia<ResTexture>::type  ResTextureArray;

//--------------------------------------------------------------------------
//! @brief 画素ベースのテクスチャを表すバイナリリソースクラスです。
//---------------------------------------------------------------------------
class ResPixelBasedTexture : public ResTexture
{
public:
    enum { TYPE_INFO = NW_GFX_RES_TYPE_INFO(ResPixelBasedTexture) };
    enum { SIGNATURE = NW_RES_SIGNATURE32('TXPB') };

    NW_RES_CTOR_INHERIT( ResPixelBasedTexture, ResTexture )

    //---------------------------------------------------------------------------
    //! @fn           s32 GetHeight() const
    //! @brief        テクスチャの高さを取得します。
    //---------------------------------------------------------------------------
    //---------------------------------------------------------------------------
    //! @fn           void SetHeight(s32 value)
    //! @brief        テクスチャの高さを設定します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_PRIMITIVE_DECL( s32, Height )        // GetHeight(), SetHeight()

    //---------------------------------------------------------------------------
    //! @fn           s32 GetWidth() const
    //! @brief        テクスチャの幅を取得します。
    //---------------------------------------------------------------------------
    //---------------------------------------------------------------------------
    //! @fn           void SetWidth(s32 value)
    //! @brief        テクスチャの幅を設定します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_PRIMITIVE_DECL( s32, Width )         // GetWidth(), SetWidth()

    //---------------------------------------------------------------------------
    //! @fn           u32 GetFormatType() const
    //! @brief        テクスチャフォーマットタイプを取得します。
    //---------------------------------------------------------------------------
    //---------------------------------------------------------------------------
    //! @fn           void SetFormatType(u32 value)
    //! @brief        テクスチャフォーマットタイプを設定します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_PRIMITIVE_DECL( u32, FormatType )    // GetFormatType(), SetFormatType()

    //---------------------------------------------------------------------------
    //! @fn           s32 GetMipmapSize() const
    //! @brief        ミップマップの数を取得します。
    //---------------------------------------------------------------------------
    //---------------------------------------------------------------------------
    //! @fn           void SetMipmapSize(s32 value)
    //! @brief        ミップマップの数を設定します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_PRIMITIVE_DECL( s32, MipmapSize )    // GetMipmapSize(), SetMipmapSize()

    //---------------------------------------------------------------------------
    //! @fn           u32 GetTextureObject() const
    //! @brief        テクスチャオブジェクトを取得します。
    //---------------------------------------------------------------------------
    //---------------------------------------------------------------------------
    //! @fn           void SetTextureObject(u32 value)
    //! @brief        テクスチャオブジェクトを設定します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_PRIMITIVE_DECL( u32, TextureObject ) // GetTextureObject(), SetTextureObject()

    //---------------------------------------------------------------------------
    //! @fn           u32 GetLocationFlag() const
    //! @brief        メモリ配置を表すフラグを取得します。
    //---------------------------------------------------------------------------
    //---------------------------------------------------------------------------
    //! @fn           void SetLocationFlag(u32 value)
    //! @brief        メモリ配置を表すフラグを設定します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_PRIMITIVE_DECL( u32, LocationFlag )  // GetLocationFlag(), SetLocationFlag()

    //---------------------------------------------------------------------------
    //! @fn           u32 GetFormatHW() const
    //! @brief        テクスチャフォーマットを取得します。
    //---------------------------------------------------------------------------
    //---------------------------------------------------------------------------
    //! @fn           void SetFormatHW(u32 value)
    //! @brief        テクスチャフォーマットを設定します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_PRIMITIVE_DECL( u32, FormatHW )      // GetFormatHW(), SetFormatHW()

    enum FormatHW
    {
        FORMAT_HW_RGBA8    = 0,     //!< 1ピクセルが4バイト、RGBAが各8ビットのフォーマットです。
        FORMAT_HW_RGB8     = 1,     //!< 1ピクセルが3バイト、RGBが各8ビットのフォーマットです。
        FORMAT_HW_RGBA5551 = 2,     //!< 1ピクセルが2バイト、RGBが各5ビット、Aが1ビットのフォーマットです。
        FORMAT_HW_RGB565   = 3,     //!< 1ピクセルが2バイト、RGBが各5,6,5ビットのフォーマットです。
        FORMAT_HW_RGBA4    = 4,     //!< 1ピクセルが2バイト、RGBAが各4ビットのフォーマットです。
        FORMAT_HW_LA8      = 5,     //!< 1ピクセルが2バイト、AlphaとLuminanceが各8ビットのフォーマットです。
        FORMAT_HW_HILO8    = 6,     //!< 1ピクセルが2バイト、X,Yが各8ビットのフォーマットです。
        FORMAT_HW_L8       = 7,     //!< 1ピクセルが1バイト、Luminanceが8ビットのフォーマットです。
        FORMAT_HW_A8       = 8,     //!< 1ピクセルが1バイト、Alphaが8ビットのフォーマットです。
        FORMAT_HW_LA4      = 9,     //!< 1ピクセルが1バイト、AlphaとLuminanceが各4ビットのフォーマットです。
        FORMAT_HW_L4       = 10,    //!< 1ピクセルが4ビット、Luminanceが4ビットのフォーマットです。
        FORMAT_HW_A4       = 11,    //!< 1ピクセルが4ビット、Alphaが4ビットのフォーマットです。
        FORMAT_HW_ETC1     = 12,    //!< 1ピクセルが4ビット相当の圧縮フォーマットです。
        FORMAT_HW_ETC1A4   = 13     //!< 1ピクセルが8ビット相当の圧縮フォーマットです。
    };
};

//--------------------------------------------------------------------------
//! @brief テクスチャのピクセルデータと解像度情報を表すバイナリリソースクラスです。
//---------------------------------------------------------------------------
class ResPixelBasedImage : public nw::ut::ResCommon< ResPixelBasedImageData >
{
public:
    NW_RES_CTOR( ResPixelBasedImage )

    //---------------------------------------------------------------------------
    //! @fn           s32 GetHeight() const
    //! @brief        ピクセルデータの高さを取得します。
    //---------------------------------------------------------------------------
    //---------------------------------------------------------------------------
    //! @fn           void SetHeight(s32 value)
    //! @brief        ピクセルデータの高さを設定します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_PRIMITIVE_DECL( s32, Height )        // GetHeight(), SetHeight()

    //---------------------------------------------------------------------------
    //! @fn           s32 GetWidth() const
    //! @brief        ピクセルデータの幅を取得します。
    //---------------------------------------------------------------------------
    //---------------------------------------------------------------------------
    //! @fn           void SetWidth(s32 value)
    //! @brief        ピクセルデータの幅を設定します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_PRIMITIVE_DECL( s32, Width )         // GetWidth(), SetWidth()

    //---------------------------------------------------------------------------
    //! @fn           s32 GetImageDataCount() const
    //! @brief        画像データのバイナリデータの要素数を取得します。
    //---------------------------------------------------------------------------
    //---------------------------------------------------------------------------
    //! @fn           u8 GetImageData(int idx) const
    //! @brief        画像データのバイナリデータを取得します。
    //---------------------------------------------------------------------------
    //---------------------------------------------------------------------------
    //! @fn           void SetImageData(int idx, u8 value)
    //! @brief        画像データのバイナリデータのリストに要素を設定します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_PRIMITIVE_LIST_DECL( u8, ImageData ) // GetImageData(), GetImageData(int idx), GetImageDataCount()

    //---------------------------------------------------------------------------
    //! @brief        コピーされたテクスチャのアドレスを取得します。
    //!
    //! @return       コピーされたテクスチャの論理アドレスです。
    //---------------------------------------------------------------------------
    u32 GetLocationAddress() const { return ref().m_LocationAddress; }

    //---------------------------------------------------------------------------
    //! @brief        コピーされたテクスチャのアドレスを設定します。
    //!
    //! @details      Setup 後には アドレスは TextureMapper 内のコマンドに格納されるので
    //!               Setup の前に設定します。
    //!
    //! @param[in]    address コピーされたテクスチャの論理アドレスです。VRAM 上のアドレスでも構いません。
    //---------------------------------------------------------------------------
    void SetLocationAddress(u32 address) { ref().m_LocationAddress = address; }
    void SetLocationAddress(const void* address) { ref().m_LocationAddress = reinterpret_cast<u32>(address); }

    //---------------------------------------------------------------------------
    //! @brief        1 ピクセルあたりのビット長を取得します。
    //---------------------------------------------------------------------------
    u32 GetBitsPerPixel() const { return ref().m_BitsPerPixel; }

    //---------------------------------------------------------------------------
    //! @brief        GPU から参照されるイメージのアドレスを取得します。
    //!
    //! @details      LocationAddess が設定されている場合はそのアドレスを使用し、
    //!               LocationAddess が NULL の場合には、ImageData のアドレスを直接 GPU から参照します。
    //!
    //! @return       GPU から参照されるイメージのアドレスです。
    //---------------------------------------------------------------------------
    u32 GetImageAddress() const
    {
        u32 locationAddress = this->GetLocationAddress();

        if ( locationAddress )
        {
            return locationAddress;
        }
        else
        {
            return reinterpret_cast<u32>( this->GetImageData() );
        }
    }

    //---------------------------------------------------------------------------
    //! @brief        テクスチャイメージのメモリ配置が不正でないかチェックします。
    //!
    //! @return       問題なければ true 問題があれば false を返します。
    //---------------------------------------------------------------------------
    bool CheckMemoryLocation() const;
};
typedef nw::ut::ResArrayClass<ResPixelBasedImage>::type        ResPixelBasedImageArray;
typedef nw::ut::ResArrayClass<const ResPixelBasedImage>::type  ResPixelBasedImageArrayConst;

//--------------------------------------------------------------------------
//! @brief 画像データによる平面テクスチャを表すバイナリリソースクラスです。
//---------------------------------------------------------------------------
class ResImageTexture : public ResPixelBasedTexture
{
public:
    enum { TYPE_INFO = NW_GFX_RES_TYPE_INFO(ResImageTexture) };
    enum { SIGNATURE = NW_RES_SIGNATURE32('TXIM') };

    NW_RES_CTOR_INHERIT( ResImageTexture, ResPixelBasedTexture )

    //---------------------------------------------------------------------------
    //! @fn           ResPixelBasedImage GetImage()
    //! @brief        ピクセルデータを取得します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_CLASS_DECL( ResPixelBasedImage, Image ) // GetImage()

    //---------------------------------------------------------------------------
    //! @brief        テクスチャイメージのアドレスを取得します。
    //!
    //! @return       テクスチャイメージの論理アドレスです。
    //---------------------------------------------------------------------------
    u32 GetLocationAddress() const { return this->GetImage().GetLocationAddress(); }

    //---------------------------------------------------------------------------
    //! @brief        展開済みのテクスチャイメージのアドレスを設定します。
    //!
    //! @details      Setup 前に設定します。
    //!               LocationFlag と LocationAddress を両方設定した場合には
    //!               LocationAddress を優先し、LocationFlag は無効となります。
    //!               LocationAddress ではテクスチャのコピーはおこないません。
    //!               nngxAddVramDmaCommand 等を利用して別途イメージの転送をおこなってください。
    //!
    //! @param[in]    address 展開済みのテクスチャイメージの論理アドレスです。VRAM 上のアドレスでも構いません。
    //---------------------------------------------------------------------------
    void SetLocationAddress(u32 address) { this->GetImage().SetLocationAddress( address ); }
    void SetLocationAddress(const void* address) { this->GetImage().SetLocationAddress( address ); }

    //! @brief 設定内容です。
    struct Description
    {
        s32 height;                 //!< テクスチャの高さです。
        s32 width;                  //!< テクスチャの幅です。
        s32 mipmapSize;             //!< ミップマップサイズです。
        u32 locationFlag;           //!< テクスチャの配置情報フラグです。
        u32 locationAddress;        //!< テクスチャの配置アドレスです。
        u32 formatHW;               //!< レジスタに設定するフォーマットの値です。
        bool executingMemoryFill;   //!< 確保したピクセル領域をゼロでクリアするかどうかを表します。
        bool isDynamicAllocation;   //!< 動的にメモリ確保を行うフラグです。

        //! @brief コンストラクタです。
        Description()
         : height(0),
           width(0),
           mipmapSize(1),
           locationFlag(NN_GX_MEM_VRAMA | GL_NO_COPY_FCRAM_DMP),
           locationAddress(0),
           formatHW(ResPixelBasedTexture::FORMAT_HW_RGBA8),
           executingMemoryFill(false),
           isDynamicAllocation(true)
        {}
    };

    //----------------------------------------
    //! @name 作成／破棄
    //@{

    //! @brief テクスチャを動的に構築するためのクラスです。
    //!        指定したテクスチャの高さ x 幅 x １ピクセルあたりのバイト数分の
    //!        メモリが確保されます。
    //!        ミップマップサイズが指定されている場合は、ミップマップのための
    //!        領域も併せて確保されます。
    class DynamicBuilder
    {
    public:
        //! コンストラクタです。
        DynamicBuilder() {}
        //! デストラクタです。
        ~DynamicBuilder() {}

        //! テクスチャの高さを設定します。
        DynamicBuilder& Height(s32 height)
        {
            m_Description.height = height;
            return *this;
        }

        //! テクスチャの幅を設定します。
        DynamicBuilder& Width(s32 width)
        {
            m_Description.width = width;
            return *this;
        }

        //! ミップマップサイズを設定します。
        //! ミップマップを使用しないときは 1 を、
        //! ミップマップを使用するときは ミップマップ数 + 1 を指定します。
        DynamicBuilder& MipmapSize(s32 mipmapSize)
        {
            m_Description.mipmapSize = mipmapSize;
            return *this;
        }

        //---------------------------------------------------------------------------
        //! @brief        テクスチャの配置情報フラグを設定します。
        //!
        //! @details      LocationFlag と LocationAddress を両方設定した場合には
        //!               LocationAddress を優先し、LocationFlag は無効となります。
        //!
        //! @param[in]    locationFlag イメージの配置メモリを指定します。
        //!
        //! @return       自インスタンスへの参照を返します。
        //---------------------------------------------------------------------------
        DynamicBuilder& LocationFlag(u32 locationFlag)
        {
            m_Description.locationFlag = locationFlag;
            return *this;
        }

        //---------------------------------------------------------------------------
        //! @brief        テクスチャの配置アドレスを設定します。
        //!
        //! @details      LocationFlag と LocationAddress を両方設定した場合には
        //!               LocationAddress を優先し、LocationFlag は無効となります。
        //!               LocationAddress ではテクスチャのコピーはおこないません。
        //!               nngxAddVramDmaCommand 等を利用して別途イメージの転送をおこなってください。
        //!
        //! @param[in]    locationAddress イメージを展開済みのアドレスを指定します。VRAM 上のアドレスでも構いません。
        //!
        //! @return       自インスタンスへの参照を返します。
        //---------------------------------------------------------------------------
        DynamicBuilder& LocationAddress(u32 locationAddress)
        {
            m_Description.locationAddress = locationAddress;
            return *this;
        }

        //! レジスタに設定するフォーマットの値を設定します。
        DynamicBuilder& Format(ResPixelBasedTexture::FormatHW format)
        {
            m_Description.formatHW = static_cast<u32>(format);
            return *this;
        }

        //! 確保したピクセル領域をゼロでクリアするかどうかを設定します。
        DynamicBuilder& ExecutingMemoryFill(bool executingMemoryFill)
        {
            m_Description.executingMemoryFill = executingMemoryFill;
            return *this;
        }

        //! @brief 動的に FCRAM 上に領域を確保するフラグを設定します。
        //!        ResImageTexture ではデフォルトで動的にメモリ確保を行います。
        DynamicBuilder& DynamicAllocation(bool isDynamicAllocation)
        {
            m_Description.isDynamicAllocation = isDynamicAllocation;
            return *this;
        }

        //! @brief        テクスチャを動的に生成します。
        //!
        //! @param[in]    allocator リソース用のメモリを解放するアロケータです。
        //!
        //! @return       生成したテクスチャを返します。
        //!
        ResImageTexture Create(os::IAllocator* allocator);

    private:
        Description m_Description;
    };

    //! @brief 動的に生成したテクスチャを破棄します。
    //!
    void DynamicDestroy();

    //@}
};

//--------------------------------------------------------------------------
//! @brief キューブテクスチャを表すバイナリリソースクラスです。
//---------------------------------------------------------------------------
class ResCubeTexture : public ResPixelBasedTexture
{
public:

    //! @brief キューブテクスチャの面を表します。
    enum CubeFace
    {
        CUBE_FACE_POSITIVE_X = 0,   //!< X 軸の＋方向です。
        CUBE_FACE_NEGATIVE_X,       //!< X 軸の－方向です。
        CUBE_FACE_POSITIVE_Y,       //!< Y 軸の＋方向です。
        CUBE_FACE_NEGATIVE_Y,       //!< Y 軸の－方向です。
        CUBE_FACE_POSITIVE_Z,       //!< Z 軸の＋方向です。
        CUBE_FACE_NEGATIVE_Z,       //!< Z 軸の－方向です。
        MAX_CUBE_FACE               //!< 面の数です。
    };

    enum { TYPE_INFO = NW_GFX_RES_TYPE_INFO(ResCubeTexture) };
    enum { SIGNATURE = NW_RES_SIGNATURE32('TXCB') };

    NW_RES_CTOR_INHERIT( ResCubeTexture, ResPixelBasedTexture )

    //---------------------------------------------------------------------------
    //! @fn           ResPixelBasedImage GetPositiveXImage()
    //! @brief        X正方向のピクセルデータを取得します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_CLASS_DECL( ResPixelBasedImage, PositiveXImage ) // GetPositiveXImage()

    //---------------------------------------------------------------------------
    //! @fn           ResPixelBasedImage GetNegativeXImage()
    //! @brief        X負方向のピクセルデータを取得します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_CLASS_DECL( ResPixelBasedImage, NegativeXImage ) // GetNegativeXImage()

    //---------------------------------------------------------------------------
    //! @fn           ResPixelBasedImage GetPositiveYImage()
    //! @brief        Y正方向のピクセルデータを取得します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_CLASS_DECL( ResPixelBasedImage, PositiveYImage ) // GetPositiveYImage()

    //---------------------------------------------------------------------------
    //! @fn           ResPixelBasedImage GetNegativeYImage()
    //! @brief        Y負方向のピクセルデータを取得します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_CLASS_DECL( ResPixelBasedImage, NegativeYImage ) // GetNegativeYImage()

    //---------------------------------------------------------------------------
    //! @fn           ResPixelBasedImage GetPositiveZImage()
    //! @brief        Z正方向のピクセルデータを取得します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_CLASS_DECL( ResPixelBasedImage, PositiveZImage ) // GetPositiveZImage()

    //---------------------------------------------------------------------------
    //! @fn           ResPixelBasedImage GetNegativeZImage()
    //! @brief        Z負方向のピクセルデータを取得します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_CLASS_DECL( ResPixelBasedImage, NegativeZImage ) // GetNegativeZImage()

    //---------------------------------------------------------------------------
    //! @brief  キューブテクスチャの面の数を取得します。
    //!
    //! @return キューブテクスチャの面の数を返します。
    //---------------------------------------------------------------------------
    s32     GetCubeFaceCount() const { return MAX_CUBE_FACE; }

    //---------------------------------------------------------------------------
    //! @brief      キューブテクスチャのイメージを取得します。
    //!
    //! @param[in]  face 取得する面です。
    //!
    //! @return     指定した面のイメージを返します。
    //---------------------------------------------------------------------------
    ResPixelBasedImage  GetImage( CubeFace face )
    {
        NW_ASSERT( 0 <= face && face < MAX_CUBE_FACE );

        return ResPixelBasedImage( ref().toImagesTables[ face ].to_ptr() );
    }

    //---------------------------------------------------------------------------
    //! @brief      キューブテクスチャのイメージを取得します。
    //!
    //! @param[in]  face 取得する面です。
    //!
    //! @return     指定した面のイメージを返します。
    //---------------------------------------------------------------------------
    const ResPixelBasedImage    GetImage( CubeFace face ) const
    {
        NW_ASSERT( 0 <= face && face < MAX_CUBE_FACE );

        return ResPixelBasedImage( ref().toImagesTables[ face ].to_ptr() );
    }

    //---------------------------------------------------------------------------
    //! @brief        テクスチャイメージのアドレスを取得します。
    //!
    //! @param[in]    face キューブテクスチャの面です。
    //!
    //! @return       テクスチャイメージの論理アドレスです。
    //---------------------------------------------------------------------------
    u32 GetLocationAddress( CubeFace face ) const { return this->GetImage( face ).GetLocationAddress(); }

    //---------------------------------------------------------------------------
    //! @brief        展開済みのテクスチャイメージのアドレスを設定します。
    //!
    //! @details      Setup 前に設定します。
    //!               LocationFlag と LocationAddress を両方設定した場合には
    //!               LocationAddress を優先し、LocationFlag は無効となります。
    //!               LocationAddress ではテクスチャのコピーはおこないません。
    //!               nngxAddVramDmaCommand 等を利用して別途イメージの転送をおこなってください。
    //!
    //! @param[in]    face    キューブテクスチャの面です。
    //! @param[in]    address 展開済みのテクスチャイメージの論理アドレスです。VRAM 上のアドレスでも構いません。
    //---------------------------------------------------------------------------
    void SetLocationAddress( CubeFace face, u32 address) { this->GetImage( face ).SetLocationAddress( address ); }
    void SetLocationAddress( CubeFace face, const void* address) { this->GetImage( face ).SetLocationAddress( address ); }
};


//--------------------------------------------------------------------------
//! @brief 画像データによるシャドウテクスチャを表すバイナリリソースクラスです。
//---------------------------------------------------------------------------
class ResShadowTexture : public ResPixelBasedTexture
{
public:
    enum { TYPE_INFO = NW_GFX_RES_TYPE_INFO(ResShadowTexture) };
    enum { SIGNATURE = NW_RES_SIGNATURE32('TXSH') };

    NW_RES_CTOR_INHERIT( ResShadowTexture, ResPixelBasedTexture )

    //---------------------------------------------------------------------------
    //! @fn           ResPixelBasedImage GetImage()
    //! @brief        ピクセルデータを取得します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_CLASS_DECL( ResPixelBasedImage, Image ) // GetImage()
    NW_RES_FIELD_BOOL_PRIMITIVE_DECL( PerspectiveShadow )      // IsPerspectiveShadow(), SetPerspectiveShadow()
    NW_RES_FIELD_PRIMITIVE_DECL( f32, ShadowZBias )    // GetShadowZBias(), SetShadowZBias()
    NW_RES_FIELD_PRIMITIVE_DECL( f32, ShadowZScale )    // GetShadowZScale(), SetShadowZScale()

    //---------------------------------------------------------------------------
    //! @brief        テクスチャイメージのアドレスを取得します。
    //!
    //! @return       テクスチャイメージの論理アドレスです。
    //---------------------------------------------------------------------------
    u32 GetLocationAddress() const { return this->GetImage().GetLocationAddress(); }

    //---------------------------------------------------------------------------
    //! @brief        展開済みのテクスチャイメージのアドレスを設定します。
    //!
    //! @details      Setup 前に設定します。
    //!               LocationFlag と LocationAddress を両方設定した場合には
    //!               LocationAddress を優先し、LocationFlag は無効となります。
    //!               LocationAddress ではテクスチャのコピーはおこないません。
    //!               nngxAddVramDmaCommand 等を利用して別途イメージの転送をおこなってください。
    //!
    //! @param[in]    address 展開済みのテクスチャイメージの論理アドレスです。VRAM 上のアドレスでも構いません。
    //---------------------------------------------------------------------------
    void SetLocationAddress(u32 address) { this->GetImage().SetLocationAddress( address ); }
    void SetLocationAddress(const void* address) { this->GetImage().SetLocationAddress( address ); }


    //! @brief 設定内容です。
    struct Description
    {
        s32 height;                 //!< テクスチャの高さです。
        s32 width;                  //!< テクスチャの幅です。
        u32 locationFlag;           //!< テクスチャの配置情報フラグです。
        u32 locationAddress;        //!< テクスチャの配置アドレスです。
        bool executingMemoryFill;   //!< 確保したピクセル領域をゼロでクリアするかどうかを表します。
        bool isPerspectiveShadow;   //!< 投影シャドウかどうかです。
        f32 shadowZBias;            //!< シャドウテクスチャの Z バイアス値です。
        f32 shadowZScale;           //!< オフセット値に乗算するスケール値です。
        bool isDynamicAllocation;   //!< 動的にメモリ確保を行うフラグです。

        //! @brief コンストラクタです。
        Description()
         : height(0),
           width(0),
           locationFlag(NN_GX_MEM_VRAMA | GL_NO_COPY_FCRAM_DMP),
           locationAddress(0),
           executingMemoryFill(false),
           isPerspectiveShadow(true),
           shadowZBias(0.0f),
           shadowZScale(1.0f),
           isDynamicAllocation(false)
        {}
    };

    //----------------------------------------
    //! @name 作成／破棄
    //@{

    //! @brief テクスチャを動的に構築するためのクラスです。
    //!        指定したテクスチャの高さ x 幅 x １ピクセルあたりのバイト数分の
    //!        メモリが確保されます。
    //!        ミップマップサイズが指定されている場合は、ミップマップのための
    //!        領域も併せて確保されます。
    class DynamicBuilder
    {
    public:
        //! コンストラクタです。
        DynamicBuilder() {}
        //! デストラクタです。
        ~DynamicBuilder() {}

        //! テクスチャの高さを設定します。
        DynamicBuilder& Height(s32 height)
        {
            m_Description.height = height;
            return *this;
        }

        //! テクスチャの幅を設定します。
        DynamicBuilder& Width(s32 width)
        {
            m_Description.width = width;
            return *this;
        }

        //---------------------------------------------------------------------------
        //! @brief        テクスチャの配置情報フラグを設定します。
        //!
        //! @details      LocationFlag と LocationAddress を両方設定した場合には
        //!               LocationAddress を優先し、LocationFlag は無効となります。
        //!
        //! @param[in]    locationFlag イメージの配置メモリを指定します。
        //!
        //! @return       自インスタンスへの参照を返します。
        //---------------------------------------------------------------------------
        DynamicBuilder& LocationFlag(u32 locationFlag)
        {
            m_Description.locationFlag = locationFlag;
            return *this;
        }

        //---------------------------------------------------------------------------
        //! @brief        テクスチャの配置アドレスを設定します。
        //!
        //! @details      LocationFlag と LocationAddress を両方設定した場合には
        //!               LocationAddress を優先し、LocationFlag は無効となります。
        //!               LocationAddress ではテクスチャのコピーはおこないません。
        //!               nngxAddVramDmaCommand 等を利用して別途イメージの転送をおこなってください。
        //!
        //! @param[in]    locationAddress イメージを展開済みのアドレスを指定します。VRAM 上のアドレスでも構いません。
        //!
        //! @return       自インスタンスへの参照を返します。
        //---------------------------------------------------------------------------
        DynamicBuilder& LocationAddress(u32 locationAddress)
        {
            m_Description.locationAddress = locationAddress;
            return *this;
        }

        //! 確保したピクセル領域をゼロでクリアするかどうかを設定します。
        DynamicBuilder& ExecutingMemoryFill(bool executingMemoryFill)
        {
            m_Description.executingMemoryFill = executingMemoryFill;
            return *this;
        }

        //! 投影シャドウかどうかを設定します。
        DynamicBuilder& PerspectiveShadow(bool isPerspectiveShadow)
        {
            m_Description.isPerspectiveShadow = isPerspectiveShadow;
            return *this;
        }

        //! シャドウテクスチャの Z バイアス値を設定します。
        DynamicBuilder& ShadowZBias(f32 shadowZBias)
        {
            m_Description.shadowZBias = shadowZBias;
            return *this;
        }

        //! オフセット値に乗算するスケール値を設定します。
        DynamicBuilder& ShadowZScale(f32 shadowZScale)
        {
            m_Description.shadowZScale = shadowZScale;
            return *this;
        }

        //! @brief 動的に FCRAM 上に領域を確保するフラグを設定します。
        //!        ResShadowTexture ではデフォルトで動的にメモリ確保を行いません。
        DynamicBuilder& DynamicAllocation(bool isDynamicAllocation)
        {
            m_Description.isDynamicAllocation = isDynamicAllocation;
            return *this;
        }

        //! @brief        テクスチャを動的に生成します。
        //!
        //! @param[in]    allocator リソース用のメモリを解放するアロケータです。
        //!
        //! @return       生成したテクスチャを返します。
        //!
        ResShadowTexture Create(os::IAllocator* allocator);

    private:
        Description m_Description;
    };

    //! @brief 動的に生成したテクスチャを破棄します。
    //!
    void DynamicDestroy();

    //@}
};

//--------------------------------------------------------------------------
//! @brief テクスチャを間接的に参照として表すバイナリリソースクラスです。
//---------------------------------------------------------------------------
class ResReferenceTexture : public ResTexture
{
public:
    enum { TYPE_INFO = NW_GFX_RES_TYPE_INFO(ResReferenceTexture) };
    enum { SIGNATURE = NW_RES_SIGNATURE32('TXRF') };

    NW_RES_CTOR_INHERIT( ResReferenceTexture, ResTexture )

    //---------------------------------------------------------------------------
    //! @fn           const char * GetPath() const
    //! @brief        参照先テクスチャを表すパスを取得します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_STRING_DECL( Path )                     // GetPath()

    //---------------------------------------------------------------------------
    //! @fn           ResTexture GetTargetTexture()
    //! @brief        参照先テクスチャを取得します。
    //---------------------------------------------------------------------------
    NW_RES_FIELD_CLASS_DECL( ResTexture, TargetTexture ) // GetTargetTexture()
};


//----------------------------------------
NW_INLINE ResTexture
ResTexture::Dereference()
{
    NW_ASSERT( this->IsValid() );

    if ( this->ref().typeInfo == ResReferenceTexture::TYPE_INFO )
    {
        return ResStaticCast<ResReferenceTexture>(*this).GetTargetTexture();
    }
    else
    {
        return *this;
    }
}

//----------------------------------------
NW_INLINE const ResTexture
ResTexture::Dereference() const
{
    NW_ASSERT( this->IsValid() );

    if ( this->ref().typeInfo == ResReferenceTexture::TYPE_INFO )
    {
        return ResStaticCast<ResReferenceTexture>(*this).GetTargetTexture();
    }
    else
    {
        return *this;
    }
}

} // namespace res
} // namespace gfx
} // namespace nw

#endif // NW_GFX_RESTEXTURE_H_