Thsfx

NDS special effect library

What is this?

This is a simple library for controlling special effects functions in the form of macros for the Nintendo DS's sprite and background hardware. These functions are available for both screens.

Where do i get it?

Currently the sources for this are part of LibThds. The source can be downloaded via SVN (see libthds page) or directly from the svn httpd:

• thsfx.h

Functions

thSfxEnable
This enables special effects on the specified screen.

• s - screen 0 ~ 1
• t - type of effect. See Effects Types below.
• a - First target layer for blending/alpha or fade effects. See Layer List below.
• b - Second target layer, which should be of lower priority than the first.

#define thSfxEnable(s, t, a, b) (REG_BLDCNT(s) = ((a)+((b)<<8)+((t)<<6)))

thSfxSetBrightness
Sets fade effect amount. For this effect only the first target set by thSfxEnable is relevant "For each pixel each R, G, B intensities are calculated separately:"
I = I1st + (31-I1st)*EVY  ;For Brightness Increase
I = I1st - (I1st)*EVY  ;For Brightness Decrease

• s - screen 0 ~ 1
• b - fade amount 0 ~ 31. 0 = no fade, 31 = fully faded (EVY)

#define thSfxSetBrightness(s, b) (REG_BLDY(s) = (b))

thSfxSetAlphaBlend
Sets blend amount. "For this effect, the top-most non-transparent pixel must be selected as 1st Target, and the next-lower non-transparent pixel must be selected as 2nd Target, if so - and only if so, then color intensities of 1st and 2nd Target are mixed together by using the parameters set by thSfxSetAlphaBlend, for each pixel each R, G, B intensities are calculated separately:"
Formula for resulting blend:
I = MIN(31, I1st*EVA + I2nd*EVB)

• s - screen 0 ~ 1
• a - target a coefficient 0 ~ 31 (EVA)
• b - target b coefficient 0 ~ 31 (EVB)

#define thSfxSetAlphaBlend(s, a, b) (REG_BLDALPHA(s)=(a)+((b)<<8))

Layer list
Here is a list of layer definitions, they may be or'd together in which case the topmost pixel of each target will be used.

• SFX_BG0 - Background 0 (or 3D engine if enabled)
• SFX_BG1 - Background 1
• SFX_BG2 - Background 2
• SFX_BG3 - Background 3
• SFX_OBJ - Hardware Sprites
• SFX_BD - Backdrop color

#define SFX_BG0 1
#define SFX_BG1 2
#define SFX_BG2 4
#define SFX_BG3 8
#define SFX_OBJ 16
#define SFX_BD  32

Effects Types

• SFX_NONE - Disables all sfx, this is the default at startup. This may also be used as a layer.
• SFX_ALPHA - Enable alpha blending of two or more layers, use thSfxSetAlphaBlend to set blend amount
• SFX_BRIGHTINC - Fade to white use thSfxSetBrightness to set amount
• SFX_BRIGHTDEC - Fade to Black use thSfxSetBrightness to set amount

#define SFX_NONE 0
#define SFX_ALPHA 1
#define SFX_BRIGHTINC 2
#define SFX_BRIGHTDEC 3

Misc Macros
These functions may be used to obtain the registers for special effects control.

• s - screen 0 ~ 1

#define REG_BLDCNT(s)   (*(uint16 *)(0x04000050+((s)*0x1000)))
#define REG_BLDALPHA(s) (*(uint16 *)(0x04000052+((s)*0x1000)))
#define REG_BLDY(s) (*(uint16 *)(0x04000054+((s)*0x1000)))

Examples

Fadeout
Fade screen 0 to black.

thSfxEnable(0, SFX_BRIGHTDEC, SFX_BG0|SFX_BG1|SFX_BG2|SFX_BG3|SFX_OBJ|SFX_BD, SFX_NONE);
int fade=0;
do {
  thSfxSetBrightness(0, fade);
  swiWaitForVBlank();
} while(++fade<=SFX_MAX);

Fade to White
Fade screen 1 to White slowly.

thSfxEnable(1, SFX_BRIGHTINC, SFX_BG0|SFX_BG1|SFX_BG2|SFX_BG3|SFX_OBJ|SFX_BD, SFX_NONE);
int fade=0;
do {
  thSfxSetBrightness(1, fade>>2);
  swiWaitForVBlank();
} while(++fade<=(SFX_MAX<<2));

Blend backgrounds with sprites
Blend sprites evenly with backgrounds

thSfxEnable(0, SFX_BRIGHTINC, SFX_OBJ, SFX_BG0|SFX_BG1|SFX_BG2|SFX_BG3|SFX_BD);
thSfxSetAlphaBlend(0, 15, 15);