report when OnDiskGif is too wide; improve OnDiskGif documentation

[TheKitty]

CircuitPython version

Adafruit CircuitPython 8.1.0beta0 on Adafruit Pyportal

Code/REPL

// Designed to decode images up to 480x320

Behavior

When gif is larger than screen, error occurs. Is this an exert? Should it throw an error or display the upper left portion of the gif?

Consider documenting on readthedocs compatibility with palletized colors vs. embedded colors. I tried reducing with a palette early on and it didn't take it. That's fine but should be documented. ezgif doesn't seem to match palette working options with those in code (rats). Maybe state that matching display and palette may make things go faster?

Consider documenting on readthedocs the max is 480x320 per the code. State if smaller GIFs than the defined display are ok and if so if they'll be in the upper left of displayio window. Throw error if > those dimensions

Description

No response

Additional information

No response

[dhalbert]

The maximum GIF width is 320 pixels, because there's a statically allocated buffer that's a single line of the image. The height is not limited, but on Pyportal Titano, if I increase the mag height to 480, 480x320 images run out of RAM. Shorter images can display, but they're pretty uncommon (I tested with 480x150, etc.).

GIFs that are too large for the display get cropped to the right and bottom.

In the long run there will be boards with more RAM that could handle larger images, so we could increase the max height, or make it dynamic. I'll open a Long Term issue for that. I will not increase the max width now because it's not useful for the common case of 480x320.

[dhalbert]

@TheKitty (or anyone): What are the exact restrictions on what kind of GIF can be used? I am not familiar with what palette, color, etc. options are possible vs what is supported. I'm just looking for a specific "your GIF has to be ...". I will add that to the doc.

[dhalbert]

@gamblor21 see previous post - you have best info about what GIF format is needed. Thanks.

[TheKitty]

I wrapped my findings into the guide to help folks. I think there should be some error handling on passing args that break things but that's just me.

[dhalbert]

@TheKitty I have a not-yet-submitted PR that will explicitly report the image width is too wide instead of just saying "Invalid file".

I edited the guide a bit to say 320 is max width instead of 480 and to discuss height.