Difference WatchUi.BitmapResource and Graphics.BitmapReference

the-ninth said:

Are these two types somehow related to the graphics pool of CIQ4+ that was discussed in another thread here?

Yes. BitmapResource is the resource itself, BitmapReference is an indirect reference to the BitmapResource in the graphics pool. Since most objects - like BitmapResource - are already passed by reference in Monkey C, you can think of a BitmapReference as a reference to a reference. [*]

If x is a BitmapReference and you call x.get(), you get the corresponding BitmapResource (which is now locked in the graphics pool).

the-ninth said:

When I define a bitmap in my resources and load it via WatchUi.loadResource, do I get a BitmapResource or a BitmapReference?

In CIQ < 4, you get a BitmapResource, in CIQ >= 4 you get a BitmapReference.

The Graphics API was changed in CIQ 4 so you *mostly* don't have to care about the difference, as the relevant dc drawing functions will accept either a FontResource/BitmapResource or a FontReference/BitmapReference, but there's a notable exception when dealing with buffered bitmaps, which is highlighted in the Graphics core topic and the Analog (watchface) SDK sample. In CIQ >= 4, you call createBufferedBitmap(), whereas in CIQ < 4, you use the BufferedBitmap constructor instead.

Analog sample snippet [I added the comments about CIQ versions]

    if (Graphics has :createBufferedBitmap) { // CIQ >= 4
        // get() used to return resource as Graphics.BufferedBitmap
        _offscreenBuffer = Graphics.createBufferedBitmap(offscreenBufferOptions).get() as BufferedBitmap;
    
        _dateBuffer = Graphics.createBufferedBitmap(dateBufferOptions).get() as BufferedBitmap;
    } else if (Graphics has :BufferedBitmap) { // CIQ >= 2.3.0  && CIQ < 4
        // If this device supports BufferedBitmap, allocate the buffers we use for drawing
        // Allocate a full screen size buffer with a palette of only 4 colors to draw
        // the background image of the watchface.  This is used to facilitate blanking
        // the second hand during partial updates of the display
        _offscreenBuffer = new Graphics.BufferedBitmap(offscreenBufferOptions);
    
        // Allocate a buffer tall enough to draw the date into the full width of the
        // screen. This buffer is also used for blanking the second hand. This full
        // color buffer is needed because anti-aliased fonts cannot be drawn into
        // a buffer with a reduced color palette
        _dateBuffer = new Graphics.BufferedBitmap(dateBufferOptions);
    } else { // CIQ < 2.3.0
        _offscreenBuffer = null;
        _dateBuffer = null;
    }

FlowState said:

Since most objects - like BitmapResource - are already passed by reference in Monkey C, you can think of a BitmapReference as a reference to a reference. [*]

[*] The only objects that are passed by value are the immutable "primitive" types, except for String, Long and Double (because they're too large), although the latter types are still immutable and still *act* like they're passed by value, for most purposes, like when "==" is used to compare them to other objects of the same type.