HAM Documentation

Home · Downloads · Your Account · Submit News

Documentation Homepage HAMLib reference Back to HAM Homepage |

# Special Effects Control Functions

## Functions

void | ham_SetFxMode (u16 source_layer, u16 target_layer, u16 fx_mode)
| Set the affected layers for alpha blending and tranparency.
void | ham_SetFxAlphaLevel (u16 source_intensity, u16 target_intensity)
| Set the tranparency/luminosity amount of FX layers.
void | ham_SetFxBrightnessLevel (u16 intensity)
| Set the brightness/darkness amount of FX layers.

## Detailed Description

This section lists a few special effects functions that are available in HAMlib, such as semi-transparency, alpha blending, brightening and darkening of BGs and Sprites.

## Function Documentation

void ham_SetFxAlphaLevel | ( | u16 | source_intensity,
|  | u16 | target_intensity
| ) |

Set the tranparency/luminosity amount of FX layers.

Parameters:

  source_intensity | the intensity of the source layer(s). Range is 0..15
  target_intensity | the intensity of the target layer(s). Range is 0..15

In order to set a certain BG/OBJs transparency attributes, make sure you first set up the affected layers/sprites to operate in transparency mode. See ham_SetFxMode() and ham_CreateObj() documentation for setting them up.

After you set up tranparent layers and made sure their priorities are correct (if in doubt, see ham_InitBg() for details about priorities of backgrounds), you can user this function to determine the luminosity of the selected source and target layers. A setting of 0 means no luminosity, a setting of 15 means maximum luminosity.

Also, please note that this function is only applicable if your FX mode is set to FX_MODE_ALPHABLEND.

See also: ham_SetFxMode() ham_CreateObj() ham_InitBg()

void ham_SetFxBrightnessLevel | ( | u16 | intensity | ) |

Set the brightness/darkness amount of FX layers.

Parameters:

  intensity | the intensity of the brightening/darkening to be applied to all layers switched on as a source layer in ham_SetFxMode() . Range is 0..15

This function can be used to control the amount of brightness increase or decrease for the the following FX Modes:

- FX_MODE_LIGHTEN
- FX_MODE_DARKEN

The intensity controls how much the effect is applied to the layers selected in ham_SetFxMode().

Please note that calling this function will have no effect if the FX Mode FX_MODE_ALPHABLEND is set.

See also: ham_SetFxMode() ham_SetFxAlphaLevel()

void ham_SetFxMode | ( | u16 | source_layer,
|  | u16 | target_layer,
|  | u16 | fx_mode
| ) |

Set the affected layers for alpha blending and tranparency.

Parameters:

  source_layer | one or many affected source layers (see description)
  target_layer | one or many affected target layers (see description)

  fx_mode

  the Blending mode you want to set
  - FX_MODE_OFF (no effects,default)
  - FX_MODE_ALPHABLEND (allows transparency between BGs and Sprites)
  - FX_MODE_LIGHTEN (allows to brighten a BG / Sprite)
  - FX_MODE_DARKEN (allows to darken a BG / Sprite)

This function will set up which parts of the GBA display system are used in special FX processing. Special effects processing always maps one or multiple source layers onto one or multiple target layers. In clear text, this means, if you want your BG0 to be half transparent in front of BG1, you need to specify BG0 as enabled in the source layer, and BG1 as enabled in the target layer. Next question, how do you fill these values in? Here is a rundown of the parameter bits:

Bit Table for both source_layer and target_layer:

      bit | meaning (if set to 1)
      ----+----------------------
       0  | enable BG0
       1  | enable BG1
       2  | enable BG2
       3  | enable BG3
       4  | enable OBJ (sprites)
       5  | enable BD
       6  | unused
       7  | unused

For example, the example above would look as follows in C code:

      ham_SetFxMode(BIT0,BIT1,FX_MODE_ALPHABLEND);

You can also select multiple source and target layers simultaneously. To make it easier for you to enter them, HAM provides a service macro for this, you can just write:

      ham_SetFxMode(FX_LAYER_SELECT(1,0,0,0,0,0),
                    FX_LAYER_SELECT(0,1,0,0,0,0),
                    FX_MODE_ALPHABLEND);

See also: ham_CreateObj() ham_InitBg() ham_SetFxAlphaLevel()

Documentation Homepage | HAMLib reference | Back to HAM Homepage
documentation created with Doxygen