[SDL] SDL_SetColorKey() Doc suggestion

Terry Hancock hancock at earthlink.net
Fri Apr 27 12:39:55 PDT 2001

After tinkering with alpha surfaces a lot, I decided
that colorkeying probably made more sense for me.

Colorkeying is probably most valuable when combined
with the 8-bit palette mode.  I'd like to verify how
this system works, however, and point out how the 
documentation could be improved a bit.

It appears from experimentation that the colorkey
actually does not recognize the *color-index* of a
palettized image (which would be the literal meaning
of the "pixel format"), but rather the *color-itself*
-- i.e. the color that it looks up in the palette for
the pixel.  In other words, the color keyed blitting
algorithm is actually doing something like this:

1) Get the pixel value (an index)
2) Retrieve the pixel color from the palette table
3) Compare to "colorkey" -- if it matches, ignore this
   pixel, otherwise proceed to copy it.

Rather than this:

1) Get the pixel value (an index)
2) Compare index to colorkey's index -- if it matches...

Given that one specifies the colorkey by the *color*
and not by the *index*, and that 32-bit colorkeyed
surfaces are also supported, this is probably the most
reasonable behavior.  And indeed, this is what it
looks like it's doing.

The *catch* is that if I modify the palette, I
have to watch out for accidentally matching the colorkey
color.  Even though the index is guaranteed not to
be the "colorkey index", I can still accidentally
match the colorkey and get "holes" in my image!

[If this isn't true, the rest of this won't make
much sense, and please tell me what else might
be going on!]

However, the documentation actually says:

> The key must be of the same pixel format as
> the surface, SDL_MapRGB is often useful for
> obtaining an acceptable value.
> If flag is SDL_SRCCOLORKEY then key is the
> transparent pixel value in the source image
> of a blit.

I consider that, for a palettized image, the
phrase "same pixel format as the surface" suggests
that it is the index, since that's what's actually
stored in the surface for each pixel.

Perhaps the documentation needs to add a brief
note about palettized images to the 
SDL_ColorKey() documentation, perhaps:

"For 8-bit palettized surfaces, the actual color
value, not the color index, will be compared to
the color key. It is therefore possible for more
than one index to indicate transparency, by
setting the palette table accordingly."

This came up because I'm using a procedural
method to modify palettes at runtime according
to a "lighting transform".  I took care to
insure that the colorkey-index was not modified,
but I still got occasional "holes" in my image.

I suspect this is because some of the other
palette entries got set (by chance) to the same
color as the colorkey.  My fix will be to
check for this and perturb the color slightly
to avoid the match, by adding 1 to each channel.


Terry Hancock
hancock at earthlink.net

More information about the SDL mailing list