Multiple calls to setDitherPattern() yields unexpected behaviors

Hey, all. I'll preface this by saying that this is largely a duplicate of a secondary issue mentioned here:

But it's been over a year and this still isn't documented anywhere, so I wanted to call it out.

When the primitive drawing color is set to white and setDitherPattern() is called the first time, it behaves mostly as expected (as noted in the docs, alpha is inverted). Not noted in the docs, however, is that this effectively resets the color to a value that behaves like black on subsequent calls to setDitherPattern(). I encountered this while trying to create a lighting mask - the first band of dithering worked as I expected but all subsequent bands misbehaved unless I made additional calls to setColor() to return the color to white. Intuitively, I would have expected the color and the dither pattern / alpha to be adjustable independent of one another.

I'm not sure that this behavior should be changed; changing it could break existing games that assume the current behavior. But it should be called out in the documentation here:

I'd add a note to indicate something along the lines of "when dithering white color patterns, calls to setDitherPattern() after the first will behave as if the color is set to black, unless you explicitly reset the color to white with setColor() before calling setDitherPattern() each time."

It is also probably worth noting under setColor() that it clears the current dithering pattern.

2 Likes