Bitmap allows pixels to be set to color indexes that exceed value_count

[FoamyGuy]

CircuitPython version

Adafruit CircuitPython 7.0.0-alpha.6 Adafruit PyPortal with samd51j20

Code/REPL

bitmap_test = displayio.Bitmap(2, 2, 3)
bitmap_test[0,0] = 3  # no error raised
bitmap_test[0,0] = 4  # raises ValueError "value requires too many bits"

# and another example: 

bitmap_test = displayio.Bitmap(2, 2, 5)
bitmap_test[0,0] = 15  # no error raised
bitmap_test[0,0] = 16  # raises ValueError "value requires too many bits"

Behavior

Setting the pixel to a color value that exceeds the value_count that was passed in the Bitmap() initialization does not raise an exception unless / until the value exceeds the maximum decimal value possible based on the number of bits needed to fit the value_count that was passed to the constructor.

Description

The value_count argument for the Bitmap constructor does not represent the literal count of values that are possible to set into the bitmap.

The documentation for this parameter here makes no reference to this behavior. It implies that the value_count is the literal maximum value that would be valid. https://circuitpython.readthedocs.io/en/latest/shared-bindings/displayio/index.html#displayio.Bitmap

Additional information

Ideally I think Bitmap should not allow setting pixels to a value that larger than the value_count that was passed in the constructor because Platte does not have this same behavior. Palettes constructor treats the value passed as the literal maximum values of colors. Which means code like this does not raise an exception and instead ends up being ambiguous about what color the pixel is going to get set to. Since the palette has a length of 3 it will not allow you to set index 3, palette[3] = 0xff0000 raises an exception :

bitmap = displayio.Bitmap(display.width, display.height, 3)
palette = displayio.Palette(3)
palette[0] = 0x000000
palette[1] = 0xffffff
palette[2] = 0xff0000

bitmap[80, 50] = 3

Looking into Bitmap inside the core it appears that the actual value_count does not get passed into shared-module, instead only the bits_per_index are passed. So it would not be possible to check for this and raise an exception unless that were modified further.

Alternatively we could document this behavior in the docs for the value_count parameter of Bitmap so that there is an explanation somewhere of how it behaves and why it ultimately allows you to pass color values higher than value_count when setting a pixel color.