It seems like the browser you are using has JavaScript disabled. As a result, the site will not function properly. We really want you to enable it so you may experience our site as we intended it. If you have no idea what we are talking about or if you need help, visit http://www.enable-javascript.com×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

Oops, it seems like you're using an old browser that we do not fully support. If you're able to, please upgrade your browser here.×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

Attach to the image library

To use the image library, you must attach to the library by calling img_lib_attach()
. When you call this function, the image library
initializes and loads the codecs that it finds listed in the img.conf configuration file.
You can customize this file to load just the codecs that your app requires.

Load the image

To load your image, follow these steps:

Open the data source for your image.

The image data
must come from a source, such as a file, TCP/IP socket, or memory buffer. This step
involves establishing the origin of the data and opening that data source. This step
may involve no work at all (that is, if it's a file already stored in memory), or it
may involve opening a file or performing some other task.

If
the image data is stored in a file, you can use the file-based image functions in the
image library to work with the data. Otherwise, you can create an input stream to
access the data. You can call io_open()
to associate an io_stream_t with the data source. Then, you can work with the image
data using the stream.

Determine the codecs that are available to handle your image.

You can retrieve a list of all codecs that are registered with the
image library by calling img_codec_list()
. If you have additional information about
the data, you can use several other functions to retrieve a smaller set of available
codecs:

MIME types and extensions don't
necessarily guarantee that the data is in a certain format. If decoding fails because
the MIME type or extension is incorrect, you should try one of the other codecs
that's returned by img_codec_list().

Choose a valid codec.

This step involves allowing the
codecs you've identified to peek at the data to determine which one can handle the
data. You can call img_decode_validate()
, which runs through the
list of codecs and indicates which codecs (if any) approved of the data. You can then
use that codec to decode the data.

Initialize the decoder.

This step notifies the
decoder of an imminent decode operation and allows it to set up any resources it may
require. Use img_decode_begin()
to perform this step. The
img_decode_begin() function initializes and
allocates the resources that the codec needs for the decode operation.

Decode frames.

Decode frames using img_decode_frame()
until you're finished or
there are no more frames to decode (for example, when img_decode_frame() returns IMG_ERR_NODATA). The img_t
structure represents a decoded frame.

Although this process may seem complicated, there are two higher-level API calls that
simplify the process:

This function takes care of all of the steps outlined above, except
for establishing the input source and associating it with an io_stream_t. This function provides the convenience of img_load_file()
but lifts the file-only restriction. Like
img_load_file(), img_load() is
limited to loading only the first frame.

Clean up allocated resources

After you finish using the image library, you should clean up the resources
by unlocking the hardware and freeing up any memory that the image library allocated in the
img_t structure. For example, consider performing the following
clean-up operations:

Use img_reset()
to free any library-allocated memory and clear
the img_t structure.

If you loaded your image in IMG_INDIRECT mode, you must free your own image buffer after calling
img_reset().

Use img_lib_detach()
to detach from the image library and free
all associated resources.

If you created an input stream manually using io_open()
, use io_close()
to close the input stream.

If you used screen buffers to display the image, free the buffers
and any associated memory that the Screen API functions used.

Last modified: 2015-05-07

Got questions about leaving a comment? Get answers from our Disqus FAQ.

1. Download the tools

Before you start developing, you'll need to visit the Downloads tab. Here you'll find downloads for the BlackBerry 10 Native SDK, BlackBerry 10 Device Simulator, and some other useful tools.

2. Try the sample apps

Now featuring a filter control, the Sample apps tab allows you to search for samples by name or by feature.

Select either the Core or Cascades radio buttons to display the samples relevant to you.

3. Educate yourself

The Documentation tab contains tons of examples, tutorials, and best practices to guide you along the path towards building an awesome app.

You can access all the documentation that you need in the left-hand navigation.

4. Start developing

The Reference tab is where you'll find essential details about how to use our APIs.

You can use the left-hand navigation to choose how you would like to browse the reference: by module, by topic, or alphabetically. If you have an idea of what you are looking for, start typing it in the Filter box.