/*---------------------------------------------------------------------------* Copyright 2010-2013 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. *---------------------------------------------------------------------------*/ // ------------------------------------------------------- // shaderUtils.h // // Declares functions for shaderUtils library. // // This library has dependencies on gx2 and pulls in GX2 // source files // ------------------------------------------------------- #ifndef _SHADERUTILS_H #define _SHADERUTILS_H #if defined(WIN32) || defined(WIN64) #include #else #include #endif #include "optflags.h" #if defined(__cplusplus) extern "C" { #endif #if !(defined _WIN32 || defined _WIN64) #define GSH2_DECLSPEC #define GSH2API GX2API #else #ifdef _EXPORTING #define GSH2_DECLSPEC __declspec(dllexport) #else #define GSH2_DECLSPEC __declspec(dllimport) #endif #define GSH2API __cdecl #endif /// @addtogroup GX2ShaderUtilsGroup /// @{ /// \brief Macro to extract the ABI ID from a packed abi_version field. /// /// This field indicates the ABI in use, and is modified to indicate library changes /// that are neither forward nor backward compatible. #define GSH2_ABI_ID(x) (((x)&0xFF800000)) /// \brief Macro to extract the ABI major version from a packed abi_version field. /// /// This field indicates major changes to the structure format that are backward compatible /// but not forward compatible. #define GSH2_ABI_MAJOR(x) ( ((x)&0x7F0000) >> 16 ) /// \brief Macro to extract the ABI minor version from a packed abi_version field. /// /// This field indicates changes to the structure format that are both forward and backward /// compatible to some extent, that is applications compiled against an old ABI minor version can /// call libraries with a newer minor ABI version, and vice-versa. An older library may /// not provide all the features of the newer one, of course, but will still produce valid /// output. #define GSH2_ABI_MINOR(x) ((x)&0xFFFF ) /// \brief Current ABI ID version. The ABI ID passed in to the /// library must exactly match the library's ABI ID, or else shaderUtils function calls will fail. /// This is packed in to GSH2_ABI_VERSION_CURRENT. #define GSH2_ABI_ID_CURRENT 0xAB800000 /// \brief Current ABI major version, as extracted by GSH2_ABI_MAJOR(). /// /// The ABI major version /// passed to the library in abi_version must be less than or equal to the library's version, e.g. an application /// compiled against ABI version 3 will work with a version 4 library, but not vice-versa; ABI major changes /// are forward compatible but not backward compatible. An example of such a change would be adding new /// fields to a structure at the end, so as to increase its size but not move any existing fields. /// /// This field is packed in to GSH2_ABI_VERSION_CURRENT. #define GSH2_ABI_MAJOR_CURRENT 1 /// \brief Current ABI minor version, as extracted by GSH2_ABI_MINOR(). /// /// The ABI minor version /// indicates changes that are both forward and backwards compatible. This means that a newer library must /// provide sensible defaults for any parts of the structure that an older application wouldn't know about (for /// example previously reserved fields that are now in use) and a newer application will work with an older library, /// although in that case some of the new fields will be ignored by the old library (but this must still result in /// correct and functional output). /// /// This field is packed in to GSH2_ABI_CURRENT. #define GSH2_ABI_MINOR_CURRENT 3 /// \brief Packed ABI version for the abi_version field. This is normally what applications should /// use to set any abi_version field in structures passed to GSH2 functions. See GSH2_ABI_ID(), /// GSH2_ABI_MAJOR() and GSH2_ABI_MINOR() for what the fields mean. #define GSH2_ABI_VERSION_CURRENT (GSH2_ABI_ID_CURRENT | (GSH2_ABI_MAJOR_CURRENT<<16) | (GSH2_ABI_MINOR_CURRENT)) /// \brief This macro checks to make sure if the ABI ID stored in x matches the current one. #define GSH2_ABI_OK(x) (GSH2_ABI_ID(x) == GSH2_ABI_ID_CURRENT) /// \brief Compatibility macro indicating the original value of the ABI (for tools that wish to /// retain compatibility with the oldest ABI) #define GSH2_ABI_VERSION3 0xAB810003 /// \brief Function to return the current ABI version /// /// \return Packed 32 bit ABI ID, MAJOR, and MINOR versions /// /// \donotcall \hostonly \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2GetABIVersion(void); /// \brief Handle to instance of shaderUtils lib (returned from GSH2Initialize) typedef void* GSH2Handle; /// \brief Supported GPU's typedef enum { GPU_VERSION_0, ///< 0 Ver1 GPU_VERSION_1, ///< 1 Ver2 GPU_VERSION_GPU7, ///< 2 Cafe (GPU7) } GSH2GPUVersion; /// \brief Library setup information typedef struct { GSH2GPUVersion gpu; // Target gpu } GSH2Setup; /// \brief Supported shader languages typedef enum { SHADERLANG_GLSL, /// GLSL SHADERLANG_ESSL, /// ESSL } GSH2ShaderLang; /// \brief Configuration options typedef union { struct { u32 forceUniformBlock : 1; ///< force uniform block usage u32 dumpShaders : 1; ///< dump pre/post optimized file u32 skipSparkDebug : 1; ///< do not dump debug data for Spark u32 optimize : 1; ///< obsolete, deprecated in favor of optFlags/optimizeFlags u32 optFlags : 1; ///< if set, GSH2CompileSetup3 field optimizeFlags contains specific flags u32 getStats : 1; ///< if set, GSH2CompileSetup3 fields vs_stats, ps_stats, gs_stats may be present }; u32 value; } GSH2Options; /// \brief Information needed to compile the shaders typedef struct { const char* vs_source; ///< VS shader source code const char* ps_source; ///< PS shader source code const char* gs_source; ///< GS shader source code const char** so_varyings; ///< stream out varyings u32 numSOVaryings; ///< number of stream out varyings GSH2Options options; ///< configuration options GSH2ShaderLang lang; ///< shader language } GSH2CompileSetup; /// \brief GPU instruction usage statistics from the AMD compiler typedef struct { /// Total hardware instructions used (control flow + ALU + TEXTURE + NOP) u32 uNumInst; /// Number of hardware GPRs used u32 uNumTempReg; /// Number of hardware clause temporaries used. These are reserved GPRs not used past the end of an ALU clause, and do not count against GPR use. u32 uNumClauseTempReg; /// The GPR pool size for this type of shader. This is the max number of GPRs that any shader can use. u32 uGPRPoolSize; /// Number of ALU Instructions used u32 uNumALUInst; /// Number of TFETCHinstructions / Tx Units used u32 uNumTfetchInst; /// Number of VFETCH instructions used; generally only dynamic indexing on uniform buffers will affect this (most VFETCHes are in the fetch shader). u32 uNumVfetchInst; /// Number of Control flow instructions used. Control flow instructions typically initiate clauses (ALU caluse, texture fetch clause, etc.) u32 uNumCflowInst; /// Number of External (API) HW ALU Constants used (the Cx registers). Mostly used for uniform variables, although 2 seem to be reserved for the compiler. u32 uNumALUConstReg; } GSH2ShaderStats; /// \brief Information needed to compile the shaders; adds more fields for Spark Enhanced Shader Support typedef struct { // NOTE: only add new fields at the end of the structure // (otherwise old tools and new SDKs will not be able to mix) const char* vs_source; ///< VS shader source code const char* ps_source; ///< PS shader source code const char* gs_source; ///< GS shader source code const char** so_varyings; ///< stream out varyings u32 numSOVaryings; ///< number of stream out varyings GSH2Options options; ///< configuration options GSH2ShaderLang lang; ///< shader language const char* vs_source_filename; ///< VS shader source code file name const char* ps_source_filename; ///< PS shader source code file name const char* gs_source_filename; ///< GS shader source code file name const char* spark_output_dir; ///< NULL for default; or directory where to write Spark data // anything below here can only be accessed if the corresponding bit is set in options // (so we know it's been set up properly by the caller) u64 optimizeFlags; ///< optimization flags; valid if options.optFlagsPresent is 1. ///< See optflags.h for definitions. GSH2ShaderStats *ps_stats; ///< shader statistics for pixel shader; valid if options.getStats is 1 GSH2ShaderStats *vs_stats; ///< shader statistics for vertex shader; valid if options.getStats is 1 GSH2ShaderStats *gs_stats; ///< shader statistics for geometry shader; valid if options.getStats is 1 } GSH2CompileSetup2; /// \brief Information needed to compile the shaders; adds more fields for compute shaders and future expansion typedef struct { u32 abi_version; ///< version of the binary interface to shaderUtils.dll const char* vs_source; ///< VS shader source code const char* ps_source; ///< PS shader source code const char* gs_source; ///< GS shader source code const char** so_varyings; ///< stream out varyings u32 numSOVaryings; ///< number of stream out varyings GSH2Options options; ///< configuration options GSH2ShaderLang lang; ///< shader language const char* vs_source_filename; ///< VS shader source code file name const char* ps_source_filename; ///< PS shader source code file name const char* gs_source_filename; ///< GS shader source code file name const char* spark_output_dir; ///< NULL for default; or directory for Spark output u64 optimizeFlags; ///< optimization flags; valid if options.optFlagsPresent is 1 ///< see optflags.h for definitions GSH2ShaderStats *ps_stats; ///< shader statistics for pixel shader; valid if options.getStats is 1 GSH2ShaderStats *vs_stats; ///< shader statistics for vertex shader; valid if options.getStats is 1 GSH2ShaderStats *gs_stats; ///< shader statistics for geometry shader; valid if options.getStats is 1 GSH2ShaderStats *cs_stats; ///< shader statistics for compute shader; valid if options.getStats is 1 const char* cs_source; ///< CS shader source code const char* cs_source_filename; ///< CS shader source code file name u64 reserved[8]; ///< reserved for future use, set to 0 } GSH2CompileSetup3; /// \brief GX2 shaders typedef struct { GX2VertexShader vs; // VS gx2 shader GX2PixelShader ps; // PS gx2 shader GX2GeometryShader gs; // GS gx2 shader } GSH2GX2Program; /// \brief GX2 shaders extended version (includes compute shaders and reserved fields) typedef struct { u32 abi_version; ///< version of the binary interface to shaderUtils GX2VertexShader vs; ///< VS gx2 vertex shader GX2PixelShader ps; ///< PS gx2 pixel shader GX2GeometryShader gs; ///< GS gx2 geometry shader GX2ComputeShader cs; ///< CS gx2 compute shader u32 reserved[7]; ///< reserved for future use, set to 0 } GSH2GX2Program3; typedef struct { GSH2GX2Program gx2Program; ///< Resulting GX2 shader objects const char* pInfoLog; ///< null terminated string that contains information about the last compilation attempt const char* pVSDump; ///< null terminated string that contains the vertex shader debug dump const char* pGSDump; ///< null terminated string that contains the geometry shader debug dump const char* pPSDump; ///< null terminated string that contains the pixel shader debug dump } GSH2CompileOutput; typedef struct { u32 abi_version; ///< for binary compatibility between shaderUtils.dll versions GSH2GX2Program3 gx2Program; ///< Resulting GX2 shader objects const char* pInfoLog; ///< null terminated string that contains information about the last compilation attempt const char* pVSDump; ///< null terminated string that contains the vertex shader debug dump const char* pGSDump; ///< null terminated string that contains the geometry shader debug dump const char* pPSDump; ///< null terminated string that contains the pixel shader debug dump const char* pCSDump; ///< null terminated string that contains the compute shader debug dump u32 reserved[8]; ///< reserved for future use, set to 0 } GSH2CompileOutput3; /// \brief GSH patching structure, used for offline display list compilation. /// typedef struct { GX2PatchType type; ///< Type of GX2 entry to patch u32 byteOffset; ///< Byte offset from the start of the /// display list to patch u32 assetID; ///< Reserved for future use, set to 0. u32 objectLoc; ///< Reserved for future use, set to 0. } GSH2PatchEntry; /// \brief Initializes the instance of shaderUtils library /// /// \note In multi-threaded use, GSH2Initialize() needs to be called n times from the main thread /// to generate n GSH2Handles, where n is the number of application threads. Each handle should /// then be used exclusively in one of the threads in calls to GSH2CompileProgram. Do not use a /// handle across multiple threads. /// \param pSetup Information needed to initialize library /// /// \donotcall \notthreadsafe \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC GSH2Handle GSH2API GSH2Initialize(GSH2Setup* pSetup); /// \brief Destroys the instance of shaderUtils library /// /// \note In multi-threaded use, GSH2Initialize() needs to be called n times from the main thread /// to generate n GSH2Handles, where n is the number of application threads. Each handle should /// then be used exclusively in one of the threads in calls to GSH2CompileProgram. Do not use a /// handle across multiple threads. GSH2Destroy() should be called n times in the main thread for /// cleanup. /// \param h handle to instance of shaderUtils lib (returned from GSH2Initialize) /// /// \donotcall \notthreadsafe \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC GX2Boolean GSH2API GSH2Destroy(GSH2Handle h); /// \brief Compile source shaders and store in GX2 shader structures. /// /// \note In multi-threaded use, the handle (h param) should be used exclusively by the current /// thread. Handles cannot be shared across multiple threads. /// \param h handle to instance of shaderUtils lib (returned from GSH2Initialize) /// \param pSetup Compile setup parameters /// \param pOutput Compiler output data /// /// \donotcall \notthreadsafe \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC GX2Boolean GSH2API GSH2CompileProgram(GSH2Handle h, GSH2CompileSetup *pSetup, GSH2CompileOutput* pOutput); /// \brief Compile source shaders and store in GX2 shader structures; adds Spark Enhanced Shader Support. /// /// \note In multi-threaded use, the handle (h param) should be used exclusively by the current /// thread. Handles cannot be shared across multiple threads. /// \param h handle to instance of shaderUtils lib (returned from GSH2Initialize) /// \param pSetup Compile setup parameters with added Spark information /// \param pOutput Compiler output data /// /// \donotcall \notthreadsafe \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC GX2Boolean GSH2API GSH2CompileProgram2(GSH2Handle h, GSH2CompileSetup2 *pSetup, GSH2CompileOutput* pOutput); /// \brief Compile source shaders and store in GX2 shader structures; adds Compute Shader Support. /// /// \note In multi-threaded use, the handle (h param) should be used exclusively by the current /// thread. Handles cannot be shared across multiple threads. /// \param h handle to instance of shaderUtils lib (returned from GSH2Initialize) /// \param pSetup Compile setup parameters with added Spark information /// \param pOutput Compiler output data /// /// \donotcall \notthreadsafe \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC GX2Boolean GSH2API GSH2CompileProgram3(GSH2Handle h, GSH2CompileSetup3 *pSetup, GSH2CompileOutput3* pOutput); /// \brief Release allocated resources for the gx2 shaders /// /// \param h handle to instance of shaderUtils lib (returned from GSH2Initialize) /// \param pGx2Program Clean up resources allocated in GSH2CompileProgram /// /// \donotcall \notthreadsafe \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC GX2Boolean GSH2API GSH2DestroyGX2Program(GSH2Handle h, GSH2GX2Program* pGx2Program); /// \brief Release allocated resources for the gx2 shaders (compute shader version) /// /// \param h handle to instance of shaderUtils lib (returned from GSH2Initialize) /// \param pGx2Program Clean up resources allocated in GSH2CompileProgram /// /// \donotcall \notthreadsafe \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC GX2Boolean GSH2API GSH2DestroyGX2Program3(GSH2Handle h, GSH2GX2Program3* pGx2Program); /// \brief Calculate the size of a fetch shader. /// /// \param num_attrib number of attribute /// \param fsType The type of fetch shader to generate /// \param tessMode Tesselation mode, only valid if type is not GX2_FETCH_SHADER_TESSELATION_NONE /// /// \donotcall \hostonly \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2CalcFetchShaderSizeEx(u32 num_attrib, GX2FetchShaderType fsType, GX2TessellationMode tessMode); /// \brief Create a fetch shader based on the given attribute stream list. /// /// \param fs User-allocated instance of \ref GX2FetchShader structure /// \param fs_buffer User-allocated aligned buffer for the fetch shader binary code /// \param count Number of attribute streams /// \param attribs User-allocated array of \ref GX2AttribStream structures containing information /// about all attribute streams /// \param type The type of fetch shader to generate /// \param tessMode Tesselation mode, only valid if type is not GX2_FETCH_SHADER_TESSELATION_NONE /// /// \donotcall \hostonly \enddonotcall /// GSH2_DECLSPEC void GSH2API GSH2InitFetchShaderEx(GX2FetchShader* fs, void* fs_buffer, u32 count, const GX2AttribStream* attribs, GX2FetchShaderType type, GX2TessellationMode tessMode); /// \brief Function to return the number of GPRs used by the Vertex Shader program output by GSH2CompileProgram /// /// \param pShader Pointer to Vertex Shader /// \return number of GPRs used by the vertex shader program /// /// \donotcall \hostonly \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2GetVertexShaderGPRs(const GX2VertexShader * pShader); /// \brief Function to return the number of GPRs used by the Geometry Shader program output by GSH2CompileProgram /// /// \param pShader Pointer to Geometry Shader /// \return number of GPRs used by the geometry shader program /// /// \donotcall \hostonly \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2GetGeometryShaderGPRs(const GX2GeometryShader * pShader); /// \brief Function to return the number of GPRs used by the Pixel Shader program output by GSH2CompileProgram /// /// \param pShader shader Pointer to Pixel Shader /// \return number of GPRs used by the pixel shader program /// /// \donotcall \hostonly \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2GetPixelShaderGPRs(const GX2PixelShader * pShader); /// \brief Function to return the number of stack entries used by the Vertex Shader program output by GSH2CompileProgram /// /// \param pShader Pointer to Vertex Shader /// \return number of stack entries used by the vertex shader program /// /// \donotcall \hostonly \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2GetVertexShaderStackEntries(const GX2VertexShader * pShader); /// \brief Function to return the number of stack entries used by the Geometry Shader program output by GSH2CompileProgram /// /// \param pShader Pointer to Geometry Shader /// \return number of stack entries used by the geometry shader program /// /// \donotcall \hostonly \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2GetGeometryShaderStackEntries(const GX2GeometryShader * pShader); /// \brief Function to return the number of stack entries used by the Pixel Shader program output by GSH2CompileProgram /// /// \param pShader Pointer to Pixel Shader /// \return number of stack entries used by the pixel shader program /// /// \donotcall \hostonly \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2GetPixelShaderStackEntries(const GX2PixelShader * pShader); /// \brief Output a Display List (DL) containing the GPU commands produced by /// the analogous GX2 API, \ref GX2SetFetchShader. Also outputs the associated /// \ref GSH2PatchEntry required for Cafe to patch the DL at runtime. Returns /// the size of the DL produced. After use, this DL must be passed to /// \ref GSH2FreeDL to free the associated memory. /// /// \param pShader GX2FetchShader input used to create DL /// \param displayList DL address created by offline GX2 API /// \param entry patch entry created by offline GX2 API /// \return number of bytes allocated for the DL /// /// \donotcall \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2CreateSetFetchShaderDL(const GX2FetchShader * pShader, void **displayList, GSH2PatchEntry *entry); /// \brief Output a Display List (DL) containing the GPU commands produced by /// the analogous GX2 API, \ref GX2SetGeometryShader. Also outputs the /// associated \ref GSH2PatchEntry's required for Cafe to patch the DL at runtime. /// Returns the size of the DL produced. After use, this DL must be passed to /// \ref GSH2FreeDL to free the associated memory. /// /// \param pShader GX2GeometryShader input used to create DL /// \param displayList DL address created by offline GX2 API /// \param entry1 first patch entry created by offline GX2 API /// \param entry2 second patch entry created by offline GX2 API /// \return number of bytes allocated for the DL /// /// \donotcall \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2CreateSetGeometryShaderDL(const GX2GeometryShader * pShader, void **displayList, GSH2PatchEntry *entry1, GSH2PatchEntry *entry2); /// \brief Output a Display List (DL) containing the GPU commands produced by /// the analogous GX2 API, \ref GX2SetPixelShader. Also outputs the associated /// \ref GSH2PatchEntry required for Cafe to patch the DL at runtime. Returns the size /// of the DL produced. After use, this DL must be passed to /// \ref GSH2FreeDL to free the associated memory. /// /// \param pShader GX2PixelShader input used to create DL /// \param displayList DL address created by offline GX2 API /// \param entry patch entry created by offline GX2 API /// \return number of bytes allocated for the DL /// /// \donotcall \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2CreateSetPixelShaderDL(const GX2PixelShader * pShader, void **displayList, GSH2PatchEntry *entry); /// \brief Output a Display List (DL) containing the GPU commands produced by /// the analogous GX2 API, \ref GX2SetVertexShader. Also outputs the associated /// \ref GSH2PatchEntry required for Cafe to patch the DL at runtime. Returns the size /// of the DL produced. After use, this DL must be passed to /// \ref GSH2FreeDL to free the associated memory. /// /// \param pShader GX2VertexShader input used to create DL /// \param displayList DL address created by offline GX2 API /// \param entry patch entry created by offline GX2 API /// \return number of bytes allocated for the DL /// /// \donotcall \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2CreateSetVertexShaderDL(const GX2VertexShader * pShader, void **displayList, GSH2PatchEntry *entry); /// \brief Output a Display List (DL) containing the GPU commands produced by /// the analogous GX2 API, \ref GX2SetComputeShader. Also outputs the /// associated GX2PatchEntry required for Cafe to patch the DL at runtime. /// Returns the size of the DL produced. After use, this DL must be passed to /// \ref GSH2FreeDL to free the associated memory. /// /// \param pShader GX2ComputeShader input used to create DL /// \param displayList DL address created by offline GX2 API /// \param entry patch entry created by offline GX2 API /// \return number of bytes allocated for the DL /// /// \donotcall \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC u32 GSH2API GSH2CreateSetComputeShaderDL(const GX2ComputeShader * pShader, void **displayList, GSH2PatchEntry *entry); /// \brief Frees an offline Display List (DL) created by GSH2. /// /// \param displayList DL address to be freed /// /// \donotcall \hostonly \userheap \enddonotcall /// GSH2_DECLSPEC void GSH2API GSH2FreeDL(void *displayList); /// @} #if defined(__cplusplus) } #endif #endif //#ifndef _SHADERUTILS_H