Acknowledged
2 months ago

Provide polyfill where needed in Toybox.Graphics.Dc API

Basically, there should be no "[view]" sections below any of Dc methods in the docs.

The context is as follows:

I really don't understand the thought process behind adding a DC method that is supported on just some devices.

What does Garmin expect to happen when someone arrives at a need to use, say, setFill(bitmap) and it's not supported on some (seemingly random) models?

It's not like my need to tile an area with a bitmap will suddenly go away because setFill is not available on VA5. Nor will I want to dumb down the design for some models. Some people might consider that OK, but imnsho that's an amateurish hackery.

The only thing that will happen, realistically, is that I will be re-implementing setFill() for devices that don't have it, i.e. I will be making a homebrew polyfill.

To put differently, these new and shiny API methods are effectively useless, unless someone just happens to be targeting specific models supported by them.

It's never the " Let's look what supports setFill and that will be our target model list ! "

It's always the " We want to do X, let's see if the API supports it for the devices we target ".

eau_de_vie
  • 1 month ago

    The requirements for drawBitmap2 and drawOffsetBitmap are a little different, so that's why the supported devices list is different when comparing the two.

    I don't have a lot of specifics, but I'll can try to summarize. The drawOffsetBitmap() method requires a GPU, so we limit it to GPU-only products—that's pretty straight-forward. However, drawBitmap2 will generally work fine on many products that don't have a GPU. For example, if a color palette is specified, something like a bitmap rotation would require a GPU to do the color mixing with surrounding pixels, so we throw exceptions in cases like this, but they aren't well-documented. There's a ticket open already to improve the documentation for this specific method to list out all of the exceptions.

  • 2 months ago in reply to FlowState

    > Based on that rationale, all CIQ 5 devices should have a GPU, but obviously that isn't the case at all.

    I'm still not sure what the case is.

    Brandon mentioned above that per-device API availability is a subject to "enhanced graphics support", but the device list for drawOffsetBitmap is shorter than that of drawBitmap2 even though the former is a subset of the latter. This is odd.

    Furthermore, drawBitmap2 is available on VA5, but setFill is not. So I'm not sure if it means that "enhanced graphics support" has multiple levels or if there is a polyfill for drawBItmap2 on VA5 or if setFill is withheld from VA5 even though it can support it. It's all clear as mud.

  • 2 months ago

    e.g. If an API method's documentation says something like "Since: API Level 4.2.1":

    - The dev needs to use an SDK that supports API 4.2.1 (otherwise the code probably won't compile or run in the sim.)

    - The device also needs to have firmware that supports (at least) CIQ 4.2.1

    Ofc the first point can easily be glossed over by always using the latest available SDK as a rule (unless it has a known bug, I guess.) So really, "Since: API Level X" just collapses to "your device needs to support CIQ version X".

  • 2 months ago

    > The fact that's API methods' availability is subject to the SDK version and, independently, to a device model is really quite messy and inconvenient to work with.

    Well, to be 100% clear, independent of device model dependencies, an API method's availability is typically subject to a minimum "(CIQ) API Level", which refers to two separate, yet related, things: the minimum required SDK and the minimum required firmware on the device.

    e.g. If an API method's documentation says something like "Since: API Level 4.2.1":

    - The dev needs to use an SDK that supports API 4.2.1 (otherwise the code probably won't compile or run in the sim.)

    - The device also needs to have firmware that supports (at least) CIQ 4.2.1

    It's definitely possible to have a situation where a device *would* have support for some new API method, but it doesn't bc its firmware hasn't been updated. This is probably one of the reasons that the device files contain minimum CIQ / firmware version numbers which are regularly updated (as long as the device itself is updated), and whenever you build an app (including a new version of an existing app), these numbers are baked into the application package so that the store can require users to have the specified minimum versions, otherwise they'll be unable to install the app. (In the past, it's also been the case that the Asia-Pacific variant of a device might be stuck at a lower CIQ / firmware version compared to the worldwide variant, either for several months to a year or so, or even permanently)

    (You may have been aware of most or all of that, but I just wanted to highlight that it's not really the right to look at "Since API Level X" as being synonymous with "Since the SDK  that supports API X")

    I def get your point tho: In a perfect world, you would just need to know the API level supported by your device in order to know most (or all) of the available CIQ features. In fact, in the past it was said that only new (at the time) devices would get CIQ 4 - one of the rationales offered for this decision (according to guesses on the forum) was that existing devices lacked a GPU, and that Garmin wanted to guarantee the availability of GPU-related functions in CIQ 4. (Note that only devices which had CIQ 4.2 got CIQ 5.) Based on that rationale, all CIQ 5 devices should have a GPU, but obviously that isn't the case at all.

  • 2 months ago in reply to Brandon.ConnectIQ

    > The best surrogate for this is in the device configs you download with SDK Manager. In the compiler.json file for each device, specifically, if enhancedGraphicsSupport is true, the device will support setFill().

    Well noted, thanks.

    > if you don't know whether your targets will support the feature

    That was my main gripe - that `if` statement in your 3-liner requires an `else` block.

    There are two options what can go in that block - a custom implementation of setFill or an alternative, dumbed-down design of what's being drawn.

    The latter is typically not an option, not if a product aims at consistency across all supported devices, which is typically the case. Meaning that devs, who target wider range of devices and need setFill-like functionality for their design will need to re-implement setFill or they won't use it at all.

    Hence the request, for setFill & Co. to be actually useful, they need to have polyfill versions on inferior devices.

    The fact that's API methods' availability is subject to the SDK version and, independently, to a device model is really quite messy and inconvenient to work with.