--- # Copyright 2025 Google LLC # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. title: Images description: | How to add image resources to a project and display them in your app. guide_group: app-resources order: 4 platform_choice: true --- Images can be displayed in a Pebble app by adding them as a project resource. They are stored in memory as a ``GBitmap`` while the app is running, and can be displayed either in a ``BitmapLayer`` or by using ``graphics_draw_bitmap_in_rect()``. ## Creating an Image In order to be compatible with Pebble, the image should be saved as a PNG file, ideally in a palettized format (see below for palette files) with the appropriate number of colors. The number of colors available on each platform is shown below: | Platform | Number of Colors | |----------|------------------| | Aplite | 2 (black and white) | | Basalt | 64 colors | | Chalk | 64 colors | ## Color Palettes Palette files for popular graphics packages that contain the 64 supported colors are available below. Use these when creating color image resources: * [Photoshop `.act`](/assets/other/pebble_colors_64.act) * [Illustrator `.ai`](/assets/other/pebble_colors_64.ai) * [GIMP `.pal`](/assets/other/pebble_colors_64.pal) * [ImageMagick `.gif`](/assets/other/pebble_colors_64.gif) ## Import the Image {% platform cloudpebble %} Add the `.png` file as a resource using the 'Add New' button next to 'Resources'. Give the resource a suitable 'Identifier' such as 'EXAMPLE_IMAGE' and click 'Save'. {% endplatform %} {% platform local %} After placing the image in the project's `resources` directory, add an entry to the `resources` item in `package.json`. Specify the `type` as `bitmap`, choose a `name` (to be used in code) and supply the path relative to the project's `resources` directory. Below is an example: ```js "resources": { "media": [ { "type": "bitmap", "name": "EXAMPLE_IMAGE", "file": "background.png" } ] }, ``` {% endplatform %} ## Specifying an Image Resource Image resources are used in a Pebble project when they are listed using the `bitmap` resource type. Resources of this type can be optimized using additional attributes: | Attribute | Description | Values | |-----------|-------------|--------| | `memoryFormat` | Optional. Determines the bitmap type. Reflects values in the `GBitmapFormat` `enum`. | `Smallest`, `SmallestPalette`, `1Bit`, `8Bit`, `1BitPalette`, `2BitPalette`, or `4BitPalette`. | | `storageFormat` | Optional. Determines the file format used for storage. Using `spaceOptimization` instead is preferred. | `pbi` or `png`. | | `spaceOptimization` | Optional. Determines whether the output resource is optimized for low runtime memory or low resource space usage. | `storage` or `memory`. | {% platform cloudpebble %} These attributes can be selected in CloudPebble from the resource's page: ![](/images/guides/app-resources/cp-bitmap-attributes.png) {% endplatform %} {% platform local %} An example usage of these attributes in `package.json` is shown below: ```js { "type": "bitmap", "name": "IMAGE_EXAMPLE", "file": "images/example_image.png" "memoryFormat": "Smallest", "spaceOptimization": "memory" } ``` {% endplatform %} On all platforms `memoryFormat` will default to `Smallest`. On Aplite `spaceOptimization` will default to `memory`, and `storage` on all other platforms. > If you specify a combination of attributes that is not supported, such as a > `1Bit` unpalettized PNG, the build will fail. Palettized 1-bit PNGs are > supported. When compared to using image resources in previous SDK versions: * `png` is equivalent to `bitmap` with no additional specifiers. * `pbi` is equivalent to `bitmap` with `"memoryFormat": "1Bit"`. * `pbi8` is equivalent to `bitmap` with `"memoryFormat": "8Bit"` and `"storageFormat": "pbi"`. Continuing to use the `png` resource type will result in a `bitmap` resource with `"storageFormat": "png"`, which is not optimized for memory usage on the Aplite platform due to less memory available in total, and is not encouraged. ## Specifying Resources Per Platform To save resource space, it is possible to include only certain image resources when building an app for specific platforms. For example, this is useful for the Aplite platform, which requires only black and white versions of images, which can be significantly smaller in size. Resources can also be selected according to platform and display shape. Read {% guide_link app-resources/platform-specific %} to learn more about how to do this. ## Displaying an Image Declare a ``GBitmap`` pointer. This will be the object type the image data is stored in while the app is running: ```c static GBitmap *s_bitmap; ``` {% platform cloudpebble %} Create the ``GBitmap``, specifying the 'Identifier' chosen earlier, prefixed with `RESOURCE_ID_`. This will manage the image data: {% endplatform %} {% platform local %} Create the ``GBitmap``, specifying the `name` chosen earlier, prefixed with `RESOURCE_ID_`. This will manage the image data: {% endplatform %} ```c s_bitmap = gbitmap_create_with_resource(RESOURCE_ID_EXAMPLE_IMAGE); ``` Declare a ``BitmapLayer`` pointer: ```c static BitmapLayer *s_bitmap_layer; ``` Create the ``BitmapLayer`` and set it to show the ``GBitmap``. Make sure to supply the correct width and height of your image in the ``GRect``, as well as using ``GCompOpSet`` to ensure color transparency is correctly applied: ```c s_bitmap_layer = bitmap_layer_create(GRect(5, 5, 48, 48)); bitmap_layer_set_compositing_mode(s_bitmap_layer, GCompOpSet); bitmap_layer_set_bitmap(s_bitmap_layer, s_bitmap); ``` Add the ``BitmapLayer`` as a child layer to the ``Window``: ```c layer_add_child(window_get_root_layer(window), bitmap_layer_get_layer(s_bitmap_layer)); ``` Destroy both the ``GBitmap`` and ``BitmapLayer`` when the app exits: ```c gbitmap_destroy(s_bitmap); bitmap_layer_destroy(s_bitmap_layer); ```