Color masking - Revision history

Apollolux: /* Averaging Colors */ API link

2013-06-02T02:14:54Z

‎Averaging Colors: API link

Apollolux: Cleanup

2013-06-02T02:14:09Z

Cleanup

Apollolux: created from http://web.archive.org/web/20110802210543/http://www.spheredev.org/wiki/Color_masking

2013-06-02T02:07:14Z

created from http://web.archive.org/web/20110802210543/http://www.spheredev.org/wiki/Color_masking

New page

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:

# Shaping the color channels of the source and destination pixel colors (e.g. SetPersonMask()).
# 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.

__TOC__

==Shaping Color Channels==
Functions known to adhere to this principle include:

* [[API:SetPersonMask|SetPersonMask]]()
* [[API:Font/setColorMask|Font.setColorMask]]()

In shaping the channels of a color, the channel multipliers are first calculated:
<syntaxhighlight>
red_factor = source.red / 255
green_factor = source.green / 255
blue_factor = source.blue / 255
</syntaxhighlight>

The factors are then used to "shape" the channels of the destination pixel:
<syntaxhighlight>
new_color.red = dest.red * red_factor
new_color.green = dest.green * green_factor
new_color.blue = dest.blue * blue_factor
</syntaxhighlight>

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:

* ApplyColorMask()

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:
<syntaxhighlight>
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
</syntaxhighlight>

For non-equal color ratios, the formulas change somewhat:
<syntaxhighlight>
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)
</syntaxhighlight>

==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:

* [[API:SetLayerMask|SetLayerMask]]()
* [[API:SetColorMask|SetColorMask]]()
* [[API:WindowStyle/setColorMask|WindowStyle.setColorMask]]()
* [[API:Image/blitMask|Image.blitMask]]()
* [[API:Image/transformBlitMask|Image.transformBlitMask]]()

==See Also==
* Sphere [[API:Color|Color object]] (includes links to info about color blending)
* [[Alpha channel]]

[[Category:Tutorials]]

@@ Line 37: / Line 37: @@
 Functions known to adhere to this principle include:
-*	ApplyColorMask()
+*	[[API:ApplyColorMask|ApplyColorMask]]()
 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.

@@ Line 1: / Line 1: @@
-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:
+[[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:
-#	Shaping the color channels of the source and destination pixel colors (e.g. SetPersonMask()).
+#	'''Shaping the color channels''' of the source and destination pixel colors (e.g. [[API:SetPersonMask|SetPersonMask]]()).
-#	Averaging the source and destination pixel colors (e.g. ApplyColorMask()). This is more commonly known as color blending.
+#	'''Averaging''' the source and destination pixel colors (e.g. [[API:ApplyColorMask|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.
+Note that <var>source</var> refers to the color used for masking, while <var>destination</var> 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.