SDL_SetColorKey() Doc suggestion

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.

no, it uses the pixel value (the index in palettized surfaces)
directly, not the colour. If you see something else you have found a
bug in SDL, or (more likely) your code

on the other hand, BlitSurface() copies colours, not pixel values;
hence the need for SDL_SetPalette() and split physical/logical palettes

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.

Thanks!–
Terry Hancock
@Terry_Hancock