[Pysdl-devel] get_shifts(), get_masks, get_losses()

[Eric J. <ea...@ri...>]

> fbref.get_shifts() -> (INT rshift, INT gshift, INT bshift, INT ashift)
>
> This function returns the bit shift information for the surface.
>
> FIXME: What does this mean? find out. 

SDL provides a general method to specify and use packed-pixel surface
formats. Every surface format is created with four channel masks:
Rmask, Gmask, Bmask and Amask, corresponding to the R, G, B, and A
channels.

A bit set in a channel mask means that that bit is used to convey
information about the level of that channel. SDL supports channel
masks that have up to eight consecutive bits set, which means that
a channel can have a range as large as 0 to 255.

Based on the channel masks that are passed in when a surface is
created, SDL derives two values for each channel: the shift and
the loss. The shift is the number of zero bits following the
rightmost bit set in the mask. The loss is 8 (max width of a
channel) minus the number of consecutive bits set in the mask.

For example, here is a green channel mask (Gmask) and its shift
and loss (Gshift and Gloss) for a 16-bit surface:

Gmask: 0000 0111 1110 0000
             |     |
             |     |<--->|  Gshift = 5 bits from rightmost bit
             |     |
             |<--->|        Gloss = 8 - 6 bits set = 2 bits lost



A pixel value is computed using the formula:

      (level >> loss) << shift

for each channel and then bitwise or'ing the results together.
This is exactly what map_rgb does for packed-pixel surfaces.

(255 >> loss) << shift should yield the channel mask.

There usually won't be a reason to get down and muck with this
stuff from PySDL. The one notable exception is if you're writing
to a surface with an alpha channel. SDL doesn't expect that
user programs will be interested in manipulating an alpha channel
directly; therefore it doesn't provide functions such as map_rgba,
get_rgba, etc. In this case, the pixel value can be computed
using the shift and the loss values.

Caveat: Although SDL computes the proper value for Aloss, it
currently does not ever use this value in any way. Alpha channels
must either be eight bits wide (Aloss == 0) or not exist at all
(Aloss == 8).