cafe/gx2/gx2Draw.h

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

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

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

// gx2Draw.h
//
// Declares draw-related function prototypes for gx2 library.

#ifndef _CAFE_GX2_DRAW_H_
#define _CAFE_GX2_DRAW_H_

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

/// @addtogroup GX2DrawGroup
/// @{

/// @addtogroup GX2DrawClearGroup
/// @{

/// \brief Clears the given render target to the specified color.
///
/// \note This API changes rendering states and disables state shadowing.
///       If you are using state shadowing, you must call
///       \ref GX2SetContextState() afterward.
///
/// \note This function clears only the single miplevel specified by
///       colorBuffer->viewMip. This function clears the number of slices
///       specified by colorBuffer->viewNumSlices starting with slice number
///       colorBuffer->viewFirstSlice.
///
/// \param colorBuffer pointer to color buffer to clear
/// \param r           Red color component of clear value
/// \param g           Green color component of clear value
/// \param b           Blue color component of clear value
/// \param a           Alpha color component of clear value
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
/// \disablesstateshadow
/// \notincompute
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2ClearColor(GX2ColorBuffer *colorBuffer,
                          f32 r, f32 g, f32 b, f32 a);

/// \brief Clear the depth/stencil surface with given depth and stencil values.
///
/// \param depthBuffer   pointer to depth/stencil buffer to clear
/// \param depthValue    Depth clear value (from 0.0 to 1.0)
/// \param stencilValue  Stencil clear value (from 0 to 255)
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
///
/// \note This function clears only the single miplevel specified by
///       depthBuffer->viewMip. This function clears the number of slices
///       specified by depthBuffer->viewNumSlices starting with slice number
///       depthBuffer->viewFirstSlice.
///
/// \note To generate valuable HiStencil pretest results while clearing the
///       stencil buffer, please see \ref GX2UTClearRectOp.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
/// \disablesstateshadow
/// \notincompute
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2ClearDepthStencilEx(GX2DepthBuffer *depthBuffer,
                                   f32 depthValue,
                                   u8 stencilValue,
                                   GX2ClearMode clearFlags);

/// \brief Clears the given render target and depth/stencil surface.
///
/// \note This API changes rendering states and disables state shadowing.
///       If you are using state shadowing, you must call
///       \ref GX2SetContextState() afterward.
/// \note Is is also necessary to call \ref GX2SetClearDepthStencil()
///       to set the depth/stencil buffer's clear values.
/// \note The colorBuffer and depthBuffer must have the same width, height, viewNumSlices,
///       and number of MSAA samples.
/// \note This function clears only the single miplevel specified by colorBuffer->viewMip for the color buffer
///       and depthBuffer->viewMip for the depth buffer.
///       colorBuffer->viewNumSlices must match depthBuffer->viewNumSlices.
///       This function clears the number of slices specified by colorBuffer->viewNumSlices starting with slice number
///       colorBuffer->viewFirstSlice, for the color buffer, and depthBuffer->viewFirstSlice, for the depth buffer.
/// \note To generate valuable HiStencil pretest results while clearing the stencil buffer,
///       please see \ref GX2UTClearSurface.
///
/// \param colorBuffer   pointer to color buffer to clear
/// \param depthBuffer   pointer to depth/stencil buffer to clear
/// \param r             Red color component of clear value
/// \param g             Green color component of clear value
/// \param b             Blue color component of clear value
/// \param a             Alpha color component of clear value
/// \param depthValue    Depth clear value (from 0.0 to 1.0)
/// \param stencilValue  Stencil clear value (from 0 to 255)
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
/// \disablesstateshadow
/// \notincompute
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2ClearBuffersEx(GX2ColorBuffer *colorBuffer,
                              GX2DepthBuffer *depthBuffer,
                              f32 r, f32 g, f32 b, f32 a,
                              f32 depthValue,
                              u8 stencilValue,
                              GX2ClearMode clearFlags);

/// \brief Clear the depth/stencil surface with saved depth and stencil values.
///
/// \param depthBuffer   pointer to depth/stencil buffer to clear
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
///
/// \note This API changes rendering states and disables state shadowing.
///       If you are using state shadowing, you must call
///       \ref GX2SetContextState() afterward
///       (when (clearFlags & (GX2_CLEAR_DEPTH|GX2_CLEAR_STENCIL)) != 0).
///
/// \note This API will use the current clearDepth and clearStencil values
///       from the \ref GX2DepthBuffer.
///
/// \note This function clears only the single miplevel specified by
///       depthBuffer->viewMip. This function clears the number of slices
///       specified by depthBuffer->viewNumSlices starting with slice number
///       depthBuffer->viewFirstSlice.
///
/// \note To generate valuable HiStencil pretest results while clearing the
///       stencil buffer, please see \ref GX2UTClearRectOp.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
/// \disablesstateshadow
/// \notincompute
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2ClearDepthStencil(GX2DepthBuffer *depthBuffer,
                                 GX2ClearMode clearFlags) {
    GX2ClearDepthStencilEx(depthBuffer, depthBuffer->clearDepth, (u8)depthBuffer->clearStencil, clearFlags);
}

/// \brief Clears the given render target and depth/stencil surface.
///
/// \note This API changes rendering states and disables state shadowing.
///       If you are using state shadowing, you must call
///       \ref GX2SetContextState() afterward.
/// \note This API will use the current clearDepth and clearStencil values
///       from the \ref GX2DepthBuffer.
/// \note The colorBuffer and depthBuffer must have the same width, height, viewNumSlices,
///       and number of MSAA samples.
/// \note This function clears only the single miplevel specified by colorBuffer->viewMip for the color buffer
///       and depthBuffer->viewMip for the depth buffer.
///       colorBuffer->viewNumSlices must match depthBuffer->viewNumSlices.
///       This function clears the number of slices specified by colorBuffer->viewNumSlices starting with slice number
///       colorBuffer->viewFirstSlice, for the color buffer, and depthBuffer->viewFirstSlice, for the depth buffer.
/// \note To generate valuable HiStencil pretest results while clearing the stencil buffer,
///       please see \ref GX2UTClearRectOp.
///
/// \param colorBuffer pointer to color buffer to clear
/// \param depthBuffer pointer to depth/stencil buffer to clear
/// \param r Red color component of clear value
/// \param g Green color component of clear value
/// \param b Blue color component of clear value
/// \param a Alpha color component of clear value
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
/// \disablesstateshadow
/// \notincompute
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2ClearBuffers(GX2ColorBuffer *colorBuffer,
                            GX2DepthBuffer *depthBuffer,
                            f32 r, f32 g, f32 b, f32 a,
                            GX2ClearMode clearFlags) {
    GX2ClearBuffersEx(colorBuffer, depthBuffer, r, g, b, a, depthBuffer->clearDepth, (u8)depthBuffer->clearStencil, clearFlags);
}

/// \brief Sets the clear values for the depth/stencil surface.
/// \note This API will write the depth/stencil clear registers. If using state
///       shadowing, ensure that state shadowing is enabled prior to this
///       API call.
///
/// \param depthBuffer pointer to depth/stencil buffer to clear
/// \param depthValue    Depth clear value (from 0.0 to 1.0)
/// \param stencilValue  Stencil clear value (from 0 to 255)
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetClearDepthStencil(GX2DepthBuffer *depthBuffer,
                                    f32 depthValue, u8 stencilValue);

/// \brief Sets the clear values for the depth surface.
/// \note This API will write the depth clear register. If using state
///       shadowing, ensure that state shadowing is enabled prior to this
///       API call.
///
/// \param depthBuffer pointer to depth/stencil buffer to clear
/// \param depthValue    Depth clear value (from 0.0 to 1.0)
void GX2API GX2SetClearDepth(GX2DepthBuffer *depthBuffer, f32 depthValue);

/// \brief Sets the clear values for the stencil surface.
/// \note This API will write the stencil clear register. If using state
///       shadowing, ensure that state shadowing is enabled prior to this
///       API call.
///
/// \param depthBuffer pointer to depth/stencil buffer to clear
/// \param stencilValue  Stencil clear value (from 0 to 255)
void GX2API GX2SetClearStencil(GX2DepthBuffer *depthBuffer, u8 stencilValue);

/// @}
/// @addtogroup GX2DrawPrimitiveGroup
/// @{

/// \brief Set up a vertex attribute buffer
///
/// \param index   Which vertex attribute buffer to set up
/// \param size    Size in bytes of this buffer
/// \param stride  Stride in bytes between the start of one vertex and the next
/// \param ptr     Address ptr to the first vertex (no alignment requirements)
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetAttribBuffer(u32 index, u32 size, u32 stride, const void* ptr);

/// \brief Set up the index value that indicates primitive restart.
/// This allows multiple triangle strips (for example) to be drawn with one call.
///
/// The initial default value is 0xffffffff (for 32-bit indices).  If you
/// use 16-bit indices, you must set a different value (such as 0xffff).
///
/// \param index   The index value to use to indicate primitive restart
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetPrimitiveRestartIndex(u32 index);

// -----------------
//  GX2DrawIndexed

/// \brief Draw indexed primitives (passing index buffer by reference) (extended version)
///
/// This is an extended version of \ref GX2DrawIndexed which adds baseVertex
/// to gl_VertexID when fetching non-instanced attribute data. It also provides
/// support for instancing.
///
/// \param mode         Type of primitive to draw
/// \param count        How many vertices to draw
/// \param indexFormat  Specifies if indices are 16-bit or 32-bit
/// \param indices      Pointer to the index buffer
/// \param baseVertex   Which vertex in vertex buffers is considered first
/// \param numInstances How many instances to draw
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2DrawIndexedEx(GX2PrimitiveType mode, u32 count,
                             GX2IndexFormat indexFormat,
                             const void* indices, u32 baseVertex,
                             u32 numInstances);

/// \brief Draw indexed primitives (passing index buffer by reference) (extended version)
///
/// This is an extended version of \ref GX2DrawIndexedEx which adds baseInstance
/// to gl_InstanceID when fetching instanced attribute data. Similarly baseVertex
/// is added to gl_VertexID when fetching non-instanced attribute data.
///
/// \param mode         Type of primitive to draw
/// \param count        How many vertices to draw
/// \param indexFormat  Specifies if indices are 16-bit or 32-bit
/// \param indices      Pointer to the index buffer
/// \param baseVertex   Which vertex in vertex buffers is considered first
/// \param numInstances How many instances to draw
/// \param baseInstance Base instance offset value
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2DrawIndexedEx2(GX2PrimitiveType mode, u32 count,
                             GX2IndexFormat indexFormat,
                             const void* indices, u32 baseVertex,
                             u32 numInstances, u32 baseInstance);

/// \brief Draw using adaptive tessellation
///
/// \param mode         Type of primitive to draw
/// \param count        How many vertices to draw
/// \param pTessFactors Tessellation factors buffer
/// \param baseVertex   Which vertex is considered first
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2DrawAdaptive(GX2PrimitiveType mode,
                                u32 count,
                                const void* pTessFactors,
                                u32 baseVertex)
{
     ASSERT(((mode == GX2_PRIMITIVE_TESSELLATE_LINES)      ||
             (mode == GX2_PRIMITIVE_TESSELLATE_TRIANGLES)  ||
             (mode == GX2_PRIMITIVE_TESSELLATE_QUADS)) &&
             "Only list primitive types are supported for adaptive tessellation.");

     GX2DrawIndexedEx(mode, count, GX2_INDEX_FORMAT_U32_LE, pTessFactors, baseVertex, 1);
}

/// \brief Draw indexed primitives (passing index buffer by reference) (simple version)
///
/// \param mode         Type of primitive to draw
/// \param count        How many vertices to draw
/// \param indexFormat  Specifies if indices are 16-bit or 32-bit
/// \param indices      Pointer to the index buffer
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2DrawIndexed(GX2PrimitiveType mode, u32 count,
                           GX2IndexFormat indexFormat, const void* indices)
{
    GX2DrawIndexedEx(mode, count, indexFormat, indices, 0, 1);
}

// -----------------
//  GX2DrawIndexedImmediate

/// \brief Draw indexed primitives (passing indices into the command buffer) (extended version)
///
/// \note baseVertex does not apply to attributes indexed by instance ID
///
/// \param mode         Type of primitive to draw
/// \param count        How many vertices to draw
/// \param indexFormat  Specifies if indices are 16-bit or 32-bit
/// \param indices      2 byte aligned pointer to the index buffer
/// \param baseVertex   Which vertex in vertex buffers is considered first
/// \param numInstances How many instances to draw
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2DrawIndexedImmediateEx(GX2PrimitiveType mode, u32 count,
                                      GX2IndexFormat indexFormat,
                                      const void* indices, u32 baseVertex,
                                      u32 numInstances);

/// \brief Draw indexed primitives (passing indices into the command buffer) (simple version)
///
/// \param mode         Type of primitive to draw
/// \param count        How many vertices to draw
/// \param indexFormat  Specifies if indices are 16-bit or 32-bit
/// \param indices      2 byte aligned pointer to the index buffer
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2DrawIndexedImmediate(GX2PrimitiveType mode, u32 count,
                                    GX2IndexFormat indexFormat,
                                    const void* indices)
{
    GX2DrawIndexedImmediateEx(mode, count, indexFormat, indices, 0, 1);
}

// -----------------
//  GX2Draw

/// \brief Draw non-indexed primitives (ie, auto-generated, consecutive indices) (extended version)
///
/// This is an extended version of \ref GX2Draw which adds firstVertex
/// to gl_VertexID when fetching non-instanced attribute data. It also provides
/// support for instancing.
///
/// \param mode         Type of primitive to draw
/// \param count        How many vertices to draw
/// \param firstVertex  Starting vertex index to draw
/// \param numInstances How many instances to draw
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2DrawEx(GX2PrimitiveType mode, u32 count, u32 firstVertex,
                      u32 numInstances);

/// \brief Draw non-indexed primitives (ie, auto-generated, consecutive indices) (extended version)
///
/// This is an extended version of \ref GX2DrawEx which adds baseInstance
/// to gl_InstanceID when fetching instanced attribute data. Similarly baseVertex
/// is added to gl_VertexID when fetching non-instanced attribute data.
///
/// \param mode         Type of primitive to draw
/// \param count        How many vertices to draw
/// \param firstVertex  Starting vertex index to draw
/// \param numInstances How many instances to draw
/// \param baseInstance Base instance offset value
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2DrawEx2(GX2PrimitiveType mode, u32 count, u32 firstVertex,
                       u32 numInstances, u32 baseInstance);

/// \brief Draw non-indexed primitives (ie, auto-generated, consecutive indices) (simple version)
///
/// \param mode         Type of primitive to draw
/// \param count        How many vertices to draw
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2Draw(GX2PrimitiveType mode, u32 count)
{
    GX2DrawEx(mode, count, 0, 1);
}

/// \brief Draw non-indexed primitives from a stream out buffer.
///
/// \note The count is determined by the HW based on the number of bytes written to the stream out
///       buffer.
///
/// \note The stream out buffer must also be set as one of the attribute buffers
///
/// \note \ref GX2SaveStreamOutContext() must be called before this function is called
///
/// \note Only the following primitive types are supported:
///          GX2_PRIMITIVE_POINTS
///          GX2_PRIMITIVE_LINES
///          GX2_PRIMITIVE_LINE_STRIP
///          GX2_PRIMITIVE_TRIANGLES
///          GX2_PRIMITIVE_TRIANGLE_STRIP
///
/// \param mode          Type of primitive to draw
/// \param pStreamOutBuf Pointer to stream out buffer structure
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2DrawStreamOut(GX2PrimitiveType mode,
                             const GX2StreamOutBuffer* pStreamOutBuf);

/// \brief Dispatch a compute vector.
///
/// This starts the execution of a \ref GX2ComputeShader. The number of work-items
/// executed is equal to (num_groups_x * num_groups_y * num_groups_z) *
/// \ref GX2_MAX_WORK_ITEMS_PER_WORK_GROUP.  This set describes a cube within
/// the work-group domain.  That cube is then subdivided for execution according to the shader layout.
///
/// \warning \p dispatchParams must be invalidated from the CPU caches using \ref GX2Invalidate.
/// \warning \p dispatchParams must not be modified until the last GX2DispatchCompute call referring to it has completed.
/// \warning num_groups_x, num_groups_y and num_groups_z must be at least 1.
/// \warning num_groups_x, num_groups_y and num_groups_z must be written in big-endian format.
///
/// \ingroup GX2ShaderComputeGroup
///
/// For more information about Compute Shaders see \ref GX2ComputePage "GX2 Compute Shaders"
///
/// \param dispatchParams Pointer to a GX2DispatchParams structure containing the num_groups_x, num_groups_y and num_groups_z to be dispatched.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2DispatchCompute(GX2DispatchParams *dispatchParams);

/// \brief Handy macro to adjust index buffer starting address
/// if you wish to start drawing from an index other than the first.
/// For 32-bit indices.
#define GX2_INDEX32_OFFSET(ptr, offset) (void*)((u32)ptr + offset*sizeof(u32))

/// \brief Handy macro to adjust index buffer starting address
/// if you wish to start drawing from an index other than the first.
/// For 16-bit indices.
#define GX2_INDEX16_OFFSET(ptr, offset) (void*)((u32)ptr + offset*sizeof(u16))

/// @}

/// @}

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // _CAFE_GX2_DRAW_H_