# Color masking

Jump to: navigation, search

Color masking is a technique used by several Sphere objects to influence the final color of their graphical output, usually over multiple pixels of different colors. It is used in Sphere (misleadingly) in two ways:

1. Shaping the color channels of the source and destination pixel colors (e.g. SetPersonMask()).
2. Averaging the source and destination pixel colors (e.g. ApplyColorMask()). This is more commonly known as color blending.

Note that source refers to the color used for masking, while destination is used to describe what the mask is being applied to.

There is an important distinction between the two. Say the masking color was pure red (RGB of (255, 0, 0)). If the destination color is mixed the first way, the output is guaranteed to have zero in the green and blue channels. In contrast, any destination color mixed the second way with red may not just be red, i.e. the green and blue may be non-zero.

Masking implies blocking of some sort, which means that the first definition is the "truer" of the two.

## Shaping Color Channels

Functions known to adhere to this principle include:

In shaping the channels of a color, the channel multipliers are first calculated:

```  red_factor = source.red   / 255
green_factor = source.green / 255
blue_factor = source.blue  / 255```

The factors are then used to "shape" the channels of the destination pixel:

```new_color.red   = dest.red   * red_factor
new_color.green = dest.green * green_factor
new_color.blue  = dest.blue  * blue_factor```

Under this principle, when pure white (255, 255, 255) is used as a mask, the colors being masked will remain unchanged. Conversely, any mask color applied to a white destination pixel will cause the new color to be exactly the color of the mask. (Read that last sentence twice if you didn't get it the first time.)

## Averaging Colors

Functions known to adhere to this principle include:

This principle is the basis of translucency techniques, making something appear semi-see-through. The idea is that colors are mixed in given proportions, to produce a color that is "in-between" the source and destination colors.

For equal color ratios, the formulas are:

```new_color.red   = (source.red   + dest.red)   * 0.5
new_color.green = (source.green + dest.green) * 0.5
new_color.blue  = (source.blue  + dest.blue)  * 0.5```

For non-equal color ratios, the formulas change somewhat:

```new_color.red   = (src.red   * src_ratio + dest.red   * dest_ratio) / (src_ratio + dest_ratio)
new_color.green = (src.green * src_ratio + dest.green * dest_ratio) / (src_ratio + dest_ratio)
new_color.blue  = (src.blue  * src_ratio + dest.blue  * dest_ratio) / (src_ratio + dest_ratio)```

## Unsorted Functions

The following functions use one of the two forms of color masking, but have not been sorted into one of the above two categories in operation: