cafe/gfd/gfdInterface.h

/*---------------------------------------------------------------------------*

  Copyright (C) Nintendo.  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.

 *---------------------------------------------------------------------------*/

// gfdInterface.h
//
// Interface for Grafhics File Formats.

#ifndef _CAFE_GFD_INTERFACE_H_
#define _CAFE_GFD_INTERFACE_H_

#ifdef __cplusplus
extern "C"
{
#endif // __cplusplus

/// @addtogroup GFDInterfaceGroup
/// @{

/// \brief Swap byte order in a 16-bit int.
#define GFD_SWAP_8_IN_16(x) (((x)>>8)|((x)<<8))

/// \brief Swap byte order in a 32-bit int.
#define GFD_SWAP_8_IN_32(x) ((((x)>>24)&0xff)|(((x)>>8)&0xff00)|(((x)<<8)&0xff0000)|(((x)<<24)&0xff000000))

/// \brief Endian swap in 16-bit int buffer.
///
/// \param pData               Input data to swap
/// \param numberElements       Number of elements
///
/// \donotcall \threadsafe \enddonotcall
///
inline void GFDEndianSwap8in16(u16 *pData, u32 numberElements)
{
    for(u32 i = 0; i < numberElements; i++)
    {
        *pData = GFD_SWAP_8_IN_16(*pData);
        pData++;
    }
}

/// \brief Endian swap in 32-bit int buffer.
///
/// \param pData               Input data to swap
/// \param numberElements       Number of elements
///
/// \donotcall \threadsafe \enddonotcall
///
inline void GFDEndianSwap8in32(u32 *pData, u32 numberElements)
{
    for(u32 i = 0; i < numberElements; i++)
    {
        *pData = GFD_SWAP_8_IN_32(*pData);
        pData++;
    }
}

/// \brief Endian Swap
///
/// \param pData               Input data to swap
/// \param numberElements       Number of elements
/// \param elemSize             Size of element
///
/// \donotcall \threadsafe \enddonotcall
///
inline void GFDEndianSwap(void *pData, u32 numberElements, GFDElementSize elemSize)
{
    switch (elemSize)
    {
    case GFD_ELEMENT_SIZE_8:
        break;
    case GFD_ELEMENT_SIZE_16:
        GFDEndianSwap8in16((u16*)pData, numberElements);
        break;
    case GFD_ELEMENT_SIZE_32:
        GFDEndianSwap8in32((u32*)pData, numberElements);
        break;
    default:
        break;
    }
}

/// \brief Get align mode of GX2 shader file (.gsh) or texture file (.gtx).
///
/// Given raw data loaded from shader file (.gsh) or texture file (.gtx),
/// returns \ref GFDAlignMode which was used in creating the file with tool.
///
/// \param pData            Input data, mapped from GX2 shader file (.gsh) or texture file (.gtx).
/// \retval                 Align mode of the file.
///
/// \donotcall \threadsafe \enddonotcall
///
GFDAlignMode GFDGetAlignMode(const void *pData);

//
// For Shader binary file (gsh)
//

/// \brief Get the number of Vertex shaders in GX2 shader file (.gsh)
///
/// Given a buffer of raw data loaded from GX2 shader file (.gsh),
/// returns the number of Vertex Shaders it contains.
/// Will return TRUE and set output parameters to zero if the file is valid format, but contains no shaders of a specified type.
///
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns Counts of Vertex Shader in the file. 0 means no vertex shader.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetVertexShaderCount(const void *pData);

/// \brief Get size to allocate a Vertex Shader Header from a block of memory loaded from GX2 shader file (.gsh)
///
/// This returns the size to allocate for a vertex shader header.
///
/// \param index                Index which vertex shader to extract.
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns size of memory to allocate for the shader header. 0 means no vertex shader header.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetVertexShaderHeaderSize(u32 index, const void *pData);

/// \brief Get size to allocate a Vertex Shader from a block of memory loaded from GX2 shader file (.gsh)
///
/// This returns the size to allocate for a vertex shader program.
///
/// \param index                Index which vertex shader to extract.
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns size of memory to allocate for the shader program. 0 means no vertex shader program.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetVertexShaderProgramSize(u32 index, const void *pData);

/// \brief Get a GX2VertexShader with actual shader data from a block of memory loaded from GX2 shader file (.gsh)
///
/// Given raw data loaded from .gsh shader file, and an initialized GX2VertexShader structure,
/// this fills the GX2VertexShader structure with data from the nth vertex shader in the file.
///
/// \param pHeader              Pointer to GX2VertexShader structure
/// \param pProgram             Pointer to shader program.  Must be aligned on 256 byte boundary.
/// \param index                Index of vertex shader to extract.
/// \param pData                Input data, mapped from GX2 shader file (.gsh).
/// \retval                     True on success, or false if data is invalid or index is out of range.
///
/// \donotcall \threadsafe \enddonotcall
///
BOOL GFDGetVertexShader(GX2VertexShader *pHeader, void *pProgram, u32 index, const void *pData);

/// \brief Get a GX2VertexShader pointer with actual shader data in a block of memory loaded from an aligned GX2 shader file (.gsh)
///
/// Given specific aligned data buffer loaded from aligned .gtx file,
/// this fills the GX2VertexShader structure with data for the nth shader in the file, and return the pointer.
///
/// \param index            Which shader to extract.
/// \param pData            Input data, mapped from GX2 shader file (.gsh).
/// \retval                 GX2VertexShader pointer with actual shader data in a block of memory
///
/// \donotcall \threadsafe \enddonotcall
///
GX2VertexShader *GFDGetVertexShaderPointer(u32 index, const void *pData);


/// \brief Get the number of Pixel shaders in GX2 shader file (.gsh)
///
/// Given a buffer of raw data loaded from GX2 shader file (.gsh),
/// returns the number of Pixel Shaders it contains.
/// Will return TRUE and set output parameters to zero if the file is valid format, but contains no shaders of a specified type.
///
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns Counts of Pixel Shader in the file. Returns 0 means no pixel shader header.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetPixelShaderCount(const void *pData);

/// \brief Get size to allocate a Pixel Shader Header from a block of memory loaded from GX2 shader file (.gsh)
///
/// This returns the size to allocate for a pixel shader header.
///
/// \param index                Index which pixel shader to extract.
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns size of memory to allocate for the shader header. 0 means no pixel shader header.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetPixelShaderHeaderSize(u32 index, const void *pData);

/// \brief Get size to allocate a Pixel Shader from a block of memory loaded from GX2 shader file (.gsh)
///
/// This returns the size to allocate for a Pixel shader.
///
/// \param index                Index which pixel shader to extract.
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns size of memory to allocate for the shader program. Returns 0 means no pixel shader program.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetPixelShaderProgramSize(u32 index, const void *pData);

/// \brief Get a GX2PixelShader with actual shader data from a block of memory loaded from GX2 shader file (.gsh)
///
/// Given raw data loaded from .gsh shader file, and an initialized GX2PixelShader structure,
/// this fills the GX2PixelShader structure with data from the nth pixel shader in the file.
///
/// \param pHeader              Pointer to GX2PixelShader structure to fill
/// \param pProgram             Pointer to shader program.  Must be aligned on 256 byte boundary.
/// \param index                Index of pixel shader to extract.
/// \param pData                Input data, mapped from GX2 shader file (.gsh).
/// \retval                     True on success, or false if data is invalid or index is out of range.
///
/// \donotcall \threadsafe \enddonotcall
///
BOOL GFDGetPixelShader(GX2PixelShader *pHeader, void *pProgram, u32 index, const void *pData);

/// \brief Get a GX2PixelShader pointer with actual shader data in a block of memory loaded from an aligned GX2 shader file (.gsh)
///
/// Given specific aligned data buffer loaded from aligned .gtx file,
/// this fills the GX2PixelShader structure with data for the nth shader in the file, and return the pointer.
///
/// \param index            Which shader to extract.
/// \param pData            Input data, mapped from GX2 shader file (.gsh).
/// \retval                 GX2PixelShader pointer with actual shader data in a block of memory
///
/// \donotcall \threadsafe \enddonotcall
///
GX2PixelShader *GFDGetPixelShaderPointer(u32 index, const void *pData);

/// \brief Get the number of Geometry shaders in GX2 shader file (.gsh)
///
/// Given a buffer of raw data loaded from GX2 shader file (.gsh),
/// returns the number of Geometry Shaders it contains.
/// Will return TRUE and set output parameters to zero if the file is valid format, but contains no shaders of a specified type.
///
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns Counts of Geometry Shader in the file. Returns 0 means no geometry shader header.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetGeometryShaderCount(const void *pData);

/// \brief Get size to allocate a Geometry Shader Header from a block of memory loaded from GX2 shader file (.gsh)
///
/// This returns the size to allocate for a geometry shader header.
///
/// \param index                Index which geometry shader to extract.
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns size of memory to allocate for the shader header. 0 means no geometry shader header.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetGeometryShaderHeaderSize(u32 index, const void *pData);

/// \brief Get size to allocate a Geometry Shader from a block of memory loaded from GX2 shader file (.gsh)
///
/// This returns the size to allocate for a Geometry shader.
///
/// \param index                Index which Geometry shader to extract.
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns size of memory to allocate for the shader program. Returns 0 means no geometry shader program.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetGeometryShaderProgramSize(u32 index, const void *pData);

/// \brief Get size to allocate a Geometry Shader from a block of memory loaded from GX2 shader file (.gsh)
///
/// This returns the size to allocate for a Geometry copy shader.
///
/// \param index                Index which Geometry shader to extract.
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns size of memory to allocate for the copy shader program. Returns 0 means no geometry shader program.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetGeometryShaderCopyProgramSize(u32 index, const void *pData);

/// \brief Get a GX2GeometryShader with actual shader data from a block of memory loaded from GX2 shader file (.gsh)
///
/// Given raw data loaded from .gsh shader file, and an initialized GX2GeometryShader structure,
/// this fills the GX2GeometryShader structure with data from the nth geometry shader in the file.
///
/// \param pHeader              Pointer to GX2GeometryShader structure to fill
/// \param pProgram             Pointer to shader program.  Must be aligned on 256 byte boundary.
/// \param pCopyProgram         Pointer to copy shader program.  Must be aligned on 256 byte boundary.
/// \param index                Index of geometry shader to extract.
/// \param pData                Input data, mapped from GX2 shader file (.gsh).
/// \retval                     True on success, or false if data is invalid or index is out of range.
///
/// \donotcall \threadsafe \enddonotcall
///
BOOL GFDGetGeometryShader(GX2GeometryShader *pHeader, void *pProgram, void *pCopyProgram, u32 index, const void *pData);

/// \brief Get a GX2GeometryShader pointer with actual shader data in a block of memory loaded from an aligned GX2 shader file (.gsh)
///
/// Given specific aligned data buffer loaded from aligned .gtx file,
/// this fills the GX2GeometryShader structure with data for the nth shader in the file, and return the pointer.
///
/// \param index            Which shader to extract.
/// \param pData            Input data, mapped from GX2 shader file (.gsh).
/// \retval                 GX2GeometryShader pointer with actual shader data in a block of memory
///
/// \donotcall \threadsafe \enddonotcall
///
GX2GeometryShader *GFDGetGeometryShaderPointer(u32 index, const void *pData);

/// \brief Get the number of Compute shaders in GX2 shader file (.gsh)
///
/// Given a buffer of raw data loaded from GX2 shader file (.gsh),
/// returns the number of Compute Shaders it contains.
/// Will return TRUE and set output parameters to zero if the file is in valid a format, but contains no shaders of a specified type.
///
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns Counts of Compute Shader in the file. 0 means no compute shader.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetComputeShaderCount(const void *pData);

/// \brief Get size to allocate a Compute Shader Header from a block of memory loaded from GX2 shader file (.gsh)
///
/// This returns the size to allocate for a compute shader header.
///
/// \param index                Index which compute shader to extract.
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns size of memory to allocate for the shader header. 0 means no compute shader header.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetComputeShaderHeaderSize(u32 index, const void *pData);

/// \brief Get size to allocate a Compute Shader from a block of memory loaded from GX2 shader file (.gsh)
///
/// This returns the size to allocate for a compute shader program.
///
/// \param index                Index which compute shader to extract.
/// \param pData                Input data, mapped from a GX2 shader file (.gsh).
/// \retval                     Returns size of memory to allocate for the shader program. 0 means no compute shader program.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetComputeShaderProgramSize(u32 index, const void *pData);

/// \brief Get a GX2ComputeShader with actual shader data from a block of memory loaded from GX2 shader file (.gsh)
///
/// Given raw data loaded from .gsh shader file, and an initialized GX2ComputeShader structure,
/// this fills the GX2ComputeShader structure with data from the nth compute shader in the file.
///
/// \param pHeader              Pointer to GX2ComputeShader structure
/// \param pProgram             Pointer to shader program.  Must be aligned on a 256 byte boundary.
/// \param index                Index of compute shader to extract.
/// \param pData                Input data, mapped from GX2 shader file (.gsh).
/// \retval                     True on success, or false if data is invalid or index is out of range.
///
/// \donotcall \threadsafe \enddonotcall
///
BOOL GFDGetComputeShader(GX2ComputeShader *pHeader, void *pProgram, u32 index, const void *pData);

/// \brief Get a GX2ComputeShader pointer with actual shader data in a block of memory loaded from an aligned GX2 shader file (.gsh)
///
/// Given a specific, aligned data buffer loaded from an aligned .gtx file,
/// this fills the GX2ComputeShader structure with data for the nth shader in the file, and returns the pointer.
///
/// \param index            Which shader to extract.
/// \param pData            Input data, mapped from GX2 shader file (.gsh).
/// \retval                 GX2ComputeShader pointer with actual shader data in a block of memory
///
/// \donotcall \threadsafe \enddonotcall
///
GX2ComputeShader *GFDGetComputeShaderPointer(u32 index, const void *pData);


//
// For Texture binary file (gtx)
//

/// \brief Get the number of Textures in GX2 texture file (.gtx)
///
/// Given a buffer of raw data loaded from GX2 texture file (.gtx),
/// returns the number of Textures it contains.
/// Will return TRUE and set output parameters to zero if the file is valid format, but contains no texture of a specified type.
///
/// \param pData                Input data, mapped from a GX2 texture file (.gtx).
/// \retval                     Returns Counts of Texture in the file.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetTextureCount(const void *pData);

/// \brief Get size to allocate a Texture Header from a block of memory loaded from GX2 texture file (.gtx)
///
/// This returns the size to allocate for a texture header.
///
/// \param index                Index which texture to extract.
/// \param pData                Input data, mapped from a GX2 texture file (.gtx).
/// \retval                     Returns size of memory to allocate for the texture header. 0 means no texture header.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetTextureHeaderSize(u32 index, const void *pData);

/// \brief Get Alignment size for allocating a Texture from a block of memory loaded from GX2 texture file (.gtx)
///
/// This returns the alignment size to allocate for a texture Image Data.
///
/// \param index                Index which texture  to extract.
/// \param pData                Input data, mapped from a GX2 texture file (.gtx).
/// \retval                     Returns alignment size to allocate for the texture image data. Returns 0 means no image data.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetTextureAlignmentSize(u32 index, const void *pData);

/// \brief Get size to allocate a Texture from a block of memory loaded from GX2 texture file (.gtx)
///
/// This returns the size to allocate for a texture Image Data.
///
/// \param index                Index which texture  to extract.
/// \param pData                Input data, mapped from a GX2 texture file (.gtx).
/// \retval                     Returns size of memory to allocate for the texture image data. Returns 0 means no image data.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetTextureImageSize(u32 index, const void *pData);

/// \brief Get size to allocate a Texture from a block of memory loaded from GX2 texture file (.gtx)
///
/// This returns the size to allocate for a texture Mipmap Image Data.
///
/// \param index                Index which texture to extract.
/// \param pData                Input data, mapped from a GX2 texture file (.gtx).
/// \retval                     Returns size of memory to allocate for the texture mipmap image data. Returns 0 means no mip image data.
///
/// \donotcall \threadsafe \enddonotcall
///
u32 GFDGetTextureMipImageSize(u32 index, const void *pData);

/// \brief Get a GX2Texture with actual texture data from a block of memory loaded from a GX2 texture file (.gtx)
///
/// Given raw data loaded from .gtx texture file, and an initialized GX2Texture structure,
/// this fills the GX2Texture structure with data for the nth texture in the file.
/// \note This function does not call \ref GX2Invalidate on the surface
///
/// \param pHeader          Pointer to GX2Texture Structure to fill
/// \param pImage           Pointer to image data
/// \param pMipImage        Pointer to mipmap image data
/// \param index            Which texture to extract.
/// \param pData            Input data, mapped from GX2 texture file (.gtx).
/// \retval                 True on success, or false if data is invalid or index is out of range.
///
/// \donotcall \threadsafe \enddonotcall
///
BOOL GFDGetTexture(GX2Texture *pHeader, void *pImage, void *pMipImage, u32 index, const void *pData);

/// \brief As per \ref GFDGetTexture but the surface is created with \ref GX2RCreateSurface.
/// \note Surface data will be invalidated after loading
///
/// \donotcall \gx2_typical \userheap \enddonotcall
///
BOOL GFDGetGX2RTexture(GX2Texture *pHeader, u32 index, const void *pData);

/// \brief Get a GX2Texture pointer with actual texture data in a block of memory loaded from an aligned GX2 texture file (.gtx)
///
/// Given specific aligned data buffer loaded from aligned .gtx file,
/// this fills the GX2Texture structure with data for the nth texture in the file, and returns the pointer.
/// \note This function does not call \ref GX2Invalidate on the surface
///
/// \param index            Which texture to extract.
/// \param pData            Input data, mapped from GX2 texture file (.gtx).
/// \retval                 GX2Texture pointer with actual texture data in a block of memory
///
/// \donotcall \threadsafe \enddonotcall
///
GX2Texture *GFDGetTexturePointer(u32 index, const void *pData);

/// \brief As per \ref GFDGetTexturePointer but the surface is wrapped with \ref GX2RCreateSurfaceUserMemory.
/// \note Surface data will be invalidated after loading
///
/// \donotcall \gx2_typical \enddonotcall
///
GX2Texture *GFDGetGX2RTexturePointer(u32 index, const void *pData);


/// @}

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // _CAFE_GFD_SHADER_H_