mirror of
https://github.com/google/pebble.git
synced 2025-05-04 17:01:40 -04:00
100 lines
3.7 KiB
C
100 lines
3.7 KiB
C
/*
|
||
* Copyright 2024 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.
|
||
*/
|
||
|
||
#pragma once
|
||
|
||
#include <stddef.h>
|
||
#include <stdint.h>
|
||
|
||
//! @file applib_resource.h
|
||
//! Wrapper functions for the resource syscalls. These functions give us a nice interface to export to 3rd party apps.
|
||
|
||
//! @addtogroup Foundation
|
||
//! @{
|
||
//! @addtogroup Resources
|
||
//! \brief Managing application resources
|
||
//!
|
||
//! Resources are data files that are bundled with your application binary and can be
|
||
//! loaded at runtime. You use resources to embed images or custom fonts in your app,
|
||
//! but also to embed any data file. Resources are always read-only.
|
||
//!
|
||
//! Resources are stored on Pebble’s flash memory and only loaded in RAM when you load
|
||
//! them. This means that you can have a large number of resources embedded inside your app,
|
||
//! even though Pebble’s RAM memory is very limited.
|
||
//!
|
||
//! See \htmlinclude UsingResources.html for information on how to embed
|
||
//! resources into your app's bundle.
|
||
|
||
//!
|
||
//! @{
|
||
|
||
#define RESOURCE_ID_FONT_FALLBACK RESOURCE_ID_GOTHIC_14
|
||
|
||
//! Opaque reference to a resource.
|
||
//! @see \ref resource_get_handle()
|
||
typedef void * ResHandle;
|
||
|
||
//! Gets the resource handle for a file identifier.
|
||
//! @param resource_id The resource ID
|
||
//!
|
||
//! The resource IDs are auto-generated by the Pebble build process, based
|
||
//! on the `appinfo.json`. The "name" field of each resource is prefixed
|
||
//! by `RESOURCE_ID_` and made visible to the application (through the
|
||
//! `build/src/resource_ids.auto.h` header which is automatically included).
|
||
//!
|
||
//! For example, given the following fragment of `appinfo.json`:
|
||
//! \code{.json}
|
||
//! ...
|
||
//! "resources" : {
|
||
//! "media": [
|
||
//! {
|
||
//! "name": "MY_ICON",
|
||
//! "file": "img/icon.png",
|
||
//! "type": "png",
|
||
//! },
|
||
//! ...
|
||
//! \endcode
|
||
//! The generated file identifier for this resource is `RESOURCE_ID_MY_ICON`.
|
||
//! To get a resource handle for that resource write:
|
||
//! \code{.c}
|
||
//! ResHandle rh = resource_get_handle(RESOURCE_ID_MY_ICON);
|
||
//! \endcode
|
||
ResHandle applib_resource_get_handle(uint32_t resource_id);
|
||
|
||
//! Gets the size of the resource given a resource handle.
|
||
//! @param h The handle to the resource
|
||
//! @return The size of the resource in bytes
|
||
size_t applib_resource_size(ResHandle h);
|
||
|
||
//! Copies the bytes for the resource with a given handle from flash storage into a given buffer.
|
||
//! @param h The handle to the resource
|
||
//! @param buffer The buffer to load the resource data into
|
||
//! @param max_length The maximum number of bytes to copy
|
||
//! @return The number of bytes actually copied
|
||
size_t applib_resource_load(ResHandle h, uint8_t *buffer, size_t max_length);
|
||
|
||
//! Copies a range of bytes from a resource with a given handle into a given buffer.
|
||
//! @param h The handle to the resource
|
||
//! @param start_offset The offset in bytes at which to start reading from the resource
|
||
//! @param buffer The buffer to load the resource data into
|
||
//! @param num_bytes The maximum number of bytes to copy
|
||
//! @return The number of bytes actually copied
|
||
size_t applib_resource_load_byte_range(
|
||
ResHandle h, uint32_t start_offset, uint8_t *buffer, size_t num_bytes);
|
||
|
||
//! @} // end addtogroup Resources
|
||
//! @} // end addtogroup Foundation
|
||
|