/// Texture filters.
typedef enum
{
- GPU_NEAREST = 0x0, ///< Nearest.
- GPU_LINEAR = 0x1, ///< Linear.
+ GPU_NEAREST = 0x0, ///< Nearest-neighbor interpolation.
+ GPU_LINEAR = 0x1, ///< Linear interpolation.
} GPU_TEXTURE_FILTER_PARAM;
/// Texture wrap modes.
/// Creates a light environment layer configuration parameter.
#define GPU_LIGHT_ENV_LAYER_CONFIG(n) ((n)+((n)==7))
-/// Creates a LC1 shadow bit parameter.
+/// Light shadow disable bits in GPUREG_LIGHT_CONFIG1.
#define GPU_LC1_SHADOWBIT(n) BIT(n)
-/// Creates a LC1 spot bit parameter.
+/// Light spot disable bits in GPUREG_LIGHT_CONFIG1.
#define GPU_LC1_SPOTBIT(n) BIT((n)+8)
-/// Creates a LC1 LUT bit parameter.
+/// LUT disable bits in GPUREG_LIGHT_CONFIG1.
#define GPU_LC1_LUTBIT(n) BIT((n)+16)
-/// Creates a LC1 attenuation bit parameter.
+/// Light distance attenuation disable bits in GPUREG_LIGHT_CONFIG1.
#define GPU_LC1_ATTNBIT(n) BIT((n)+24)
/// Creates a light permutation parameter.
#define GPU_LIGHTPERM(i,n) ((n) << (i))
/// Creates a light color parameter from red, green, and blue components.
#define GPU_LIGHTCOLOR(r,g,b) (((b) & 0xFF) | (((g) << 10) & 0xFF) | (((r) << 20) & 0xFF))
-/// FRESNEL options.
+/// Fresnel options.
typedef enum
{
GPU_NO_FRESNEL = 0, ///< None.
typedef enum
{
GPU_BUMP_NOT_USED = 0, ///< Disabled.
- GPU_BUMP_AS_BUMP = 1, ///< Bump as bump.
- GPU_BUMP_AS_TANG = 2, ///< Bump as tang.
+ GPU_BUMP_AS_BUMP = 1, ///< Bump as bump mapping.
+ GPU_BUMP_AS_TANG = 2, ///< Bump as tangent/normal mapping.
} GPU_BUMPMODE;
/// LUT IDs.
typedef enum
{
- GPU_LUT_D0 = 0, ///< LUT D0.
- GPU_LUT_D1 = 1, ///< LUT D1.
- GPU_LUT_SP = 2, ///< LUT SP.
- GPU_LUT_FR = 3, ///< LUT FR.
- GPU_LUT_RB = 4, ///< LUT RB.
- GPU_LUT_RG = 5, ///< LUT RG.
- GPU_LUT_RR = 6, ///< LUT RR.
- GPU_LUT_DA = 7, ///< LUT DA.
+ GPU_LUT_D0 = 0, ///< D0 LUT.
+ GPU_LUT_D1 = 1, ///< D1 LUT.
+ GPU_LUT_SP = 2, ///< Spotlight LUT.
+ GPU_LUT_FR = 3, ///< Fresnel LUT.
+ GPU_LUT_RB = 4, ///< Reflection-Blue LUT.
+ GPU_LUT_RG = 5, ///< Reflection-Green LUT.
+ GPU_LUT_RR = 6, ///< Reflection-Red LUT.
+ GPU_LUT_DA = 7, ///< Distance attenuation LUT.
} GPU_LIGHTLUTID;
/// LUT inputs.
typedef enum
{
- GPU_LUTINPUT_NH = 0, ///< Input NH.
- GPU_LUTINPUT_VH = 1, ///< Input VH.
- GPU_LUTINPUT_NV = 2, ///< Input NV.
- GPU_LUTINPUT_LN = 3, ///< Input LN.
- GPU_LUTINPUT_SP = 4, ///< Input SP.
- GPU_LUTINPUT_CP = 5, ///< Input CP.
+ GPU_LUTINPUT_NH = 0, ///< Normal*HalfVector
+ GPU_LUTINPUT_VH = 1, ///< View*HalfVector
+ GPU_LUTINPUT_NV = 2, ///< Normal*View
+ GPU_LUTINPUT_LN = 3, ///< LightVector*Normal
+ GPU_LUTINPUT_SP = 4, ///< -LightVector*SpotlightVector
+ GPU_LUTINPUT_CP = 5, ///< cosine of phi
} GPU_LIGHTLUTINPUT;
/// LUT scalers.
/// LUT selection.
typedef enum
{
- GPU_LUTSELECT_COMMON = 0, ///< Common.
- GPU_LUTSELECT_SP = 1, ///< SP.
- GPU_LUTSELECT_DA = 2, ///< DA.
+ GPU_LUTSELECT_COMMON = 0, ///< LUTs that are common to all lights.
+ GPU_LUTSELECT_SP = 1, ///< Spotlight LUT.
+ GPU_LUTSELECT_DA = 2, ///< Distance attenuation LUT.
} GPU_LIGHTLUTSELECT;
/// Supported primitives.
/**
* @file gpu-old.h
- * @brief Deprecated GPU functions.
+ * @brief Deprecated GPU functions which should not be used in new code.
+ * @description These functions have been superseeded by direct GPU register writes, or external GPU libraries.
* @deprecated
*/
#pragma once
/**
* @brief Initializes the GPU.
* @param gsphandle GSP handle to use.
+ * @deprecated
*/
void GPU_Init(Handle *gsphandle) DEPRECATED;
* @param gxbuf GX command buffer to use.
* @param gpuBuf GPU command buffer to use.
* @param gpuBufSize GPU command buffer size.
+ * @deprecated
*/
void GPU_Reset(u32* gxbuf, u32* gpuBuf, u32 gpuBufSize) DEPRECATED;
* @param startreg Start of the uniform register to set.
* @param data Data to set.
* @param numreg Number of registers to set.
+ * @deprecated
*/
void GPU_SetFloatUniform(GPU_SHADER_TYPE type, u32 startreg, u32* data, u32 numreg) DEPRECATED;
* @param y Y of the viewport.
* @param w Width of the viewport.
* @param h Height of the viewport.
+ * @deprecated
*/
void GPU_SetViewport(u32* depthBuffer, u32* colorBuffer, u32 x, u32 y, u32 w, u32 h) DEPRECATED;
* @param y Y of the scissor region.
* @param w Width of the scissor region.
* @param h Height of the scissor region.
+ * @deprecated
*/
void GPU_SetScissorTest(GPU_SCISSORMODE mode, u32 x, u32 y, u32 w, u32 h) DEPRECATED;
* @brief Sets the depth map.
* @param zScale Z scale to use.
* @param zOffset Z offset to use.
+ * @deprecated
*/
void GPU_DepthMap(float zScale, float zOffset) DEPRECATED;
* @param enable Whether to enable alpha testing.
* @param function Test function to use.
* @param ref Reference value to use.
+ * @deprecated
*/
void GPU_SetAlphaTest(bool enable, GPU_TESTFUNC function, u8 ref) DEPRECATED;
* @param enable Whether to enable depth testing.
* @param function Test function to use.
* @param writemask Pixel write mask to use.
+ * @deprecated
*/
void GPU_SetDepthTestAndWriteMask(bool enable, GPU_TESTFUNC function, GPU_WRITEMASK writemask) DEPRECATED;
* @param ref Reference value to use.
* @param input_mask Input mask to use.
* @param write_mask Write mask to use.
+ * @deprecated
*/
void GPU_SetStencilTest(bool enable, GPU_TESTFUNC function, u8 ref, u8 input_mask, u8 write_mask) DEPRECATED;
* @param sfail Operator to use on source test failure.
* @param dfail Operator to use on destination test failure.
* @param pass Operator to use on test passing.
+ * @deprecated
*/
void GPU_SetStencilOp(GPU_STENCILOP sfail, GPU_STENCILOP dfail, GPU_STENCILOP pass) DEPRECATED;
/**
* @brief Sets the face culling mode.
* @param mode Face culling mode to use.
+ * @deprecated
*/
void GPU_SetFaceCulling(GPU_CULLMODE mode) DEPRECATED;
* @note Only the first four TEV stages can write to the combiner buffer.
* @param rgb_config RGB configuration to use.
* @param alpha_config Alpha configuration to use.
+ * @deprecated
*/
void GPU_SetCombinerBufferWrite(u8 rgb_config, u8 alpha_config) DEPRECATED;
* @param colorDst Destination factor of color components.
* @param alphaSrc Source factor of the alpha component.
* @param alphaDst Destination factor of the alpha component.
+ * @deprecated
*/
void GPU_SetAlphaBlending(GPU_BLENDEQUATION colorEquation, GPU_BLENDEQUATION alphaEquation,
GPU_BLENDFACTOR colorSrc, GPU_BLENDFACTOR colorDst,
* @brief Sets the color logic operator.
* @note Cannot be used with GPU_SetAlphaBlending.
* @param op Operator to set.
+ * @deprecated
*/
void GPU_SetColorLogicOp(GPU_LOGICOP op) DEPRECATED;
* @param g Green component.
* @param b Blue component.
* @param a Alpha component.
+ * @deprecated
*/
void GPU_SetBlendingColor(u8 r, u8 g, u8 b, u8 a) DEPRECATED;
* @param bufferOffsets Offsets of the buffers.
* @param bufferPermutations Buffer permutations.
* @param bufferNumAttributes Numbers of attributes of the buffers.
+ * @deprecated
*/
void GPU_SetAttributeBuffers(u8 totalAttributes, u32* baseAddress, u64 attributeFormats, u16 attributeMask, u64 attributePermutation, u8 numBuffers, u32 bufferOffsets[], u64 bufferPermutations[], u8 bufferNumAttributes[]) DEPRECATED;
/**
* @brief Sets the enabled texture units.
* @param units Units to enable. OR texture unit values together to create this value.
+ * @deprecated
*/
void GPU_SetTextureEnable(GPU_TEXUNIT units) DEPRECATED;
* @param height Height of the texture.
* @param Parameters of the texture, such as filters and wrap modes.
* @param colorType Color type of the texture.
+ * @deprecated
*/
void GPU_SetTexture(GPU_TEXUNIT unit, u32* data, u16 width, u16 height, u32 param, GPU_TEXCOLOR colorType) DEPRECATED;
* @brief Sets the border color of a texture unit.
* @param unit Texture unit to use.
* @param borderColor The color used for the border when using the @ref GPU_CLAMP_TO_BORDER wrap mode.
+ * @deprecated
*/
void GPU_SetTextureBorderColor(GPU_TEXUNIT unit,u32 borderColor) DEPRECATED;
* @param rgbCombine RGB combiner function.
* @param alphaCombine Alpha combiner function.
* @param constantColor Constant color to provide.
+ * @deprecated
*/
void GPU_SetTexEnv(u8 id, u16 rgbSources, u16 alphaSources, u16 rgbOperands, u16 alphaOperands, GPU_COMBINEFUNC rgbCombine, GPU_COMBINEFUNC alphaCombine, u32 constantColor) DEPRECATED;
* @param primitive Primitive to draw.
* @param first First vertex to draw.
* @param count Number of vertices to draw.
+ * @deprecated
*/
void GPU_DrawArray(GPU_Primitive_t primitive, u32 first, u32 count) DEPRECATED;
* @param primitive Primitive to draw.
* @param indexArray Array of vertex indices to use.
* @param n Number of vertices to draw.
+ * @deprecated
*/
void GPU_DrawElements(GPU_Primitive_t primitive, u32* indexArray, u32 n) DEPRECATED;
-/// Finishes drawing.
+/**
+ * @brief Finishes drawing.
+ * @deprecated
+ */
void GPU_FinishDrawing() DEPRECATED;
/**
* @file channel.h
- * @brief NDSP channels.
+ * @brief Functions for interacting with DSP audio channels.
*/
#pragma once
///@name Data types
///@{
-/// Supported NDSP encodings.
+/// Supported sample encodings.
enum
{
NDSP_ENCODING_PCM8 = 0, ///< PCM8
NDSP_ENCODING_ADPCM, ///< DSPADPCM (GameCube format)
} NDSP_Encoding;
-/// Creates a hardware channel value from a channel number.
+/// Specifies the number of channels used in a sample.
#define NDSP_CHANNELS(n) ((u32)(n) & 3)
-/// Creates a hardware encoding value from an encoding type.
+/// Specifies the encoding used in a sample.
#define NDSP_ENCODING(n) (((u32)(n) & 3) << 2)
-/// NDSP playback flags.
+/// Channel format flags for use with ndspChnSetFormat.
enum
{
NDSP_FORMAT_MONO_PCM8 = NDSP_CHANNELS(1) | NDSP_ENCODING(NDSP_ENCODING_PCM8), ///< Buffer contains Mono PCM8.
// Flags
NDSP_FRONT_BYPASS = BIT(4), ///< Front bypass.
- NDSP_3D_SURROUND_PREPROCESSED = BIT(6), ///< Preprocessed 3D surround sound.
+ NDSP_3D_SURROUND_PREPROCESSED = BIT(6), ///< (?) Unknown, under research
} NDSP_Flags;
///@}
///@{
/**
* @brief Resets a channel.
- * @param id ID of the channel.
+ * @param id ID of the channel (0..23).
*/
void ndspChnReset(int id);
/**
* @brief Initializes the parameters of a channel.
- * @param id ID of the channel.
+ * @param id ID of the channel (0..23).
*/
void ndspChnInitParams(int id);
/**
* @brief Checks whether a channel is currently playing.
- * @param id ID of the channel.
+ * @param id ID of the channel (0..23).
* @return Whether the channel is currently playing.
*/
bool ndspChnIsPlaying(int id);
/**
* @brief Gets the current sample position of a channel.
- * @param id ID of the channel.
+ * @param id ID of the channel (0..23).
* @return The channel's sample position.
*/
u32 ndspChnGetSamplePos(int id);
/**
- * @brief Gets the current wave buffer sequence position of a channel.
- * @param id ID of the channel.
- * @return The channel's wave buffer sequence position.
+ * @brief Gets the sequence ID of the wave buffer that is currently playing in a channel.
+ * @param id ID of the channel (0..23).
+ * @return The sequence ID of the wave buffer.
*/
u16 ndspChnGetWaveBufSeq(int id);
///@}
/**
* @brief Sets the format of a channel.
* @sa NDSP_Encoding
- * @param id ID of the channel.
+ * @param id ID of the channel (0..23).
* @param format Format to use.
*/
void ndspChnSetFormat(int id, u16 format);
/**
- * @brief Sets the linear interpolation type of a channel.
- * @param id ID of the channel.
- * @param type Linear interpolation type to use.
+ * @brief Sets the interpolation type of a channel.
+ * @param id ID of the channel (0..23).
+ * @param type Interpolation type to use.
*/
void ndspChnSetInterp(int id, int type);
/**
* @brief Sets the sample rate of a channel.
- * @param id ID of the channel.
+ * @param id ID of the channel (0..23).
* @param rate Sample rate to use.
*/
void ndspChnSetRate(int id, float rate);
/**
- * @brief Sets the mix parameters of a channel.
- * @param id ID of the channel.
- * @param mix Mix parameters to use.
+ * @brief Sets the mix parameters (volumes) of a channel.
+ * @param id ID of the channel (0..23).
+ * @param mix Mix parameters to use. Working hypothesis:
+ * - 0: Front left volume.
+ * - 1: Front right volume.
+ * - 2: Back left volume:
+ * - 3: Back right volume:
+ * - 4..7: Same as 0..3, but for auxiliary output 0.
+ * - 8..11: Same as 0..3, but for auxiliary output 1.
*/
void ndspChnSetMix(int id, float mix[12]);
/**
- * @brief Sets the ADPCM coefficients of a channel.
- * @param id ID of the channel.
- * @param coefs ADPCM coefficients to use.
+ * @brief Sets the DSPADPCM coefficients of a channel.
+ * @param id ID of the channel (0..23).
+ * @param coefs DSPADPCM coefficients to use.
*/
void ndspChnSetAdpcmCoefs(int id, u16 coefs[16]);
///@}
///@name Wave buffers
///@{
/**
- * @brief Clears the wave buffers of a channel.
- * @param id ID of the channel.
+ * @brief Clears the wave buffer queue of a channel and stops playback.
+ * @param id ID of the channel (0..23).
*/
void ndspChnWaveBufClear(int id);
/**
- * @brief Adds a wave buffer to a channel.
- * @param id ID of the channel.
+ * @brief Adds a wave buffer to the wave buffer queue of a channel.
+ * @remark If the channel's wave buffer queue was empty before the use of this function, playback is started.
+ * @param id ID of the channel (0..23).
* @param buf Wave buffer to add.
*/
void ndspChnWaveBufAdd(int id, ndspWaveBuf* buf);
///@name IIR filters
///@{
/**
- * @brief Sets whether the mono filter of a channel is enabled.
- * @param id ID of the channel.
- * @param enable Whether to enable the mono filter.
+ * @brief Configures whether the IIR mono filter of a channel is enabled.
+ * @param id ID of the channel (0..23).
+ * @param enable Whether to enable the IIR mono filter.
*/
void ndspChnIirMonoSetEnable(int id, bool enable);
// ndspChnIirMonoSetParams
/**
- * @brief Sets whether the biquad filter of a channel is enabled.
- * @param id ID of the channel.
- * @param enable Whether to enable the biquad filter.
+ * @brief Configures whether the IIR biquad filter of a channel is enabled.
+ * @param id ID of the channel (0..23).
+ * @param enable Whether to enable the IIR biquad filter.
*/
void ndspChnIirBiquadSetEnable(int id, bool enable);
// ndspChnIirBiquadSetParams
/**
* @file ndsp.h
- * @brief Nintendo default DSP interface.
+ * @brief Interface for Nintendo's default DSP component.
*/
#pragma once
/// ADPCM data.
typedef struct
{
- u16 index; ///< Current sample index(?)
- s16 history0; ///< First previous sample index(?)
- s16 history1; ///< Second previous sample index(?)
+ u16 index; ///< Current predictor index
+ s16 history0; ///< Last outputted PCM16 sample.
+ s16 history1; ///< Second to last outputted PCM16 sample.
} ndspAdpcmData;
/// Wave buffer type.
{
union
{
- s8* data_pcm8; ///< PCM8 data.
- s16* data_pcm16; ///< PCM16 data.
- u8* data_adpcm; ///< ADPCM data.
+ s8* data_pcm8; ///< Pointer to PCM8 sample data.
+ s16* data_pcm16; ///< Pointer to PCM16 sample data.
+ u8* data_adpcm; ///< Pointer to DSPADPCM sample data.
u32 data_vaddr; ///< Data virtual address.
};
- u32 nsamples; ///< Total samples.
+ u32 nsamples; ///< Total number of samples (PCM8=bytes, PCM16=halfwords, DSPADPCM=nibbles without frame headers)
ndspAdpcmData* adpcm_data; ///< ADPCM data.
u32 offset; ///< Buffer offset. Only used for capture.
bool looping; ///< Whether to loop the buffer.
u8 padding; ///< Padding.
- u16 sequence_id; ///< Sequence ID. Used internally.
- ndspWaveBuf* next; ///< Next buffer. Used internally.
+ u16 sequence_id; ///< Sequence ID. Assigned automatically by ndspChnWaveBufAdd.
+ ndspWaveBuf* next; ///< Next buffer to play. Used internally, do not modify.
};
-/// NDSP callback function. (data = User provided data)
+/// Sound frame callback function. (data = User provided data)
typedef void (*ndspCallback)(void* data);
-/// NDSP auxiliary callback function. (data = User provided data, nsamples = Number of samples, samples = Sample data)
+/// Auxiliary output callback function. (data = User provided data, nsamples = Number of samples, samples = Sample data)
typedef void (*ndspAuxCallback)(void* data, int nsamples, void* samples[4]);
///@}
void ndspExit(void);
/**
- * @brief Gets the number of dropped NDSP frames.
- * @return The number of dropped frames.
+ * @brief Gets the number of dropped sound frames.
+ * @return The number of dropped sound frames.
*/
u32 ndspGetDroppedFrames(void);
/**
- * @brief Gets the total NDSP frame count.
- * @return The total frame count.
+ * @brief Gets the total sound frame count.
+ * @return The total sound frame count.
*/
u32 ndspGetFrameCount(void);
///@}
void ndspSetCapture(ndspWaveBuf* capture);
/**
- * @brief Sets the NDSP frame callback.
+ * @brief Sets the sound frame callback.
* @param callback Callback to set.
* @param data User-defined data to pass to the callback.
*/
///@name Auxiliary output
///@{
/**
- * @brief Sets whether an auxiliary output is enabled.
+ * @brief Configures whether an auxiliary output is enabled.
* @param id ID of the auxiliary output.
* @param enable Whether to enable the auxiliary output.
*/
void ndspAuxSetEnable(int id, bool enable);
/**
- * @brief Sets whether an auxiliary output should use front bypass.
+ * @brief Configures whether an auxiliary output should use front bypass.
* @param id ID of the auxiliary output.
* @param bypass Whether to use front bypass.
*/
void ndspAuxSetVolume(int id, float volume);
/**
- * @brief Sets the NDSP frame callback of an auxiliary output.
+ * @brief Sets the callback of an auxiliary output.
* @param id ID of the auxiliary output.
* @param callback Callback to set.
* @param data User-defined data to pass to the callback.
projects / corbenik / ctrulib.git / commitdiff