Image handling


Typedefs

typedef void image_loaded_cb (sp_image *image, void *userdata)

Enumerations

enum  sp_imageformat {
  SP_IMAGE_FORMAT_UNKNOWN = -1,
  SP_IMAGE_FORMAT_RGB = 0,
  SP_IMAGE_FORMAT_BGR = 1,
  SP_IMAGE_FORMAT_RGBA = 2,
  SP_IMAGE_FORMAT_RGBA_PRE = 3,
  SP_IMAGE_FORMAT_BGRA = 4,
  SP_IMAGE_FORMAT_BGRA_PRE = 5
}

Functions

sp_imagesp_image_create (sp_session *session, const byte image_id[20])
void sp_image_add_load_callback (sp_image *image, image_loaded_cb *callback, void *userdata)
void sp_image_remove_load_callback (sp_image *image, image_loaded_cb *callback, void *userdata)
bool sp_image_is_loaded (sp_image *image)
sp_error sp_image_error (sp_image *image)
int sp_image_width (sp_image *image)
int sp_image_height (sp_image *image)
sp_imageformat sp_image_format (sp_image *image)
void * sp_image_lock_pixels (sp_image *image, int *pitch)
void sp_image_unlock_pixels (sp_image *image)
const byte * sp_image_image_id (sp_image *image)
void sp_image_add_ref (sp_image *image)
void sp_image_release (sp_image *image)

Typedef Documentation

typedef void image_loaded_cb(sp_image *image, void *userdata)

The type of a callback used to notify the application that an image is done loading.


Enumeration Type Documentation

Image format

Enumerator:
SP_IMAGE_FORMAT_UNKNOWN  Unknown image format.
SP_IMAGE_FORMAT_RGB  24 bit image in RGB form
SP_IMAGE_FORMAT_BGR  24 bit image in BGR form
SP_IMAGE_FORMAT_RGBA  32 bit image in RGBA form
SP_IMAGE_FORMAT_RGBA_PRE  32 bit image in RGBA form with premultiplied alpha channel
SP_IMAGE_FORMAT_BGRA  32 bit image in BGRA form
SP_IMAGE_FORMAT_BGRA_PRE  32 bit image in BGRA form with premultiplied alpha channel


Function Documentation

void sp_image_add_load_callback ( sp_image image,
image_loaded_cb callback,
void *  userdata 
)

Add a callback that will be invoked when the image is loaded

If an image is loaded, and loading fails, the image will behave like an empty image.

Here is a snippet from track.c:

    g_image = sp_image_create(session, image_id);

    if (!g_image) {
        fprintf(stderr, "The cover image could not be loaded!\n");
        logout(session);
        return;
    }

    sp_image_add_load_callback(g_image, &print_cover, session);

Parameters:
[in] image Image object
[in] callback Callback that will be called when image has been fetched.
[in] userdata Opaque pointer passed to callback
Examples:
track.c.

void sp_image_add_ref ( sp_image image  ) 

Increase the reference count of an image

Parameters:
[in] image The image object

sp_image* sp_image_create ( sp_session session,
const byte  image_id[20] 
)

Create an image object

Here is a snippet from track.c:

    image_id = sp_album_cover(album);

    if (!image_id) {
        fprintf(stderr, "No album coverart!\n");
        logout(session);
        return;
    }

    g_image = sp_image_create(session, image_id);

    if (!g_image) {
        fprintf(stderr, "The cover image could not be loaded!\n");
        logout(session);
        return;
    }

Parameters:
[in] session Session
[in] image_id Spotify image ID
Returns:
Pointer to an image object. To free the object, use sp_image_release()
See also:
sp_album_cover

sp_artistbrowse_portrait

Examples:
track.c.

sp_error sp_image_error ( sp_image image  ) 

Check if image retrieval returned an error code.

Parameters:
[in] image Image object
Returns:
Error code

sp_imageformat sp_image_format ( sp_image image  ) 

Get image format

Parameters:
[in] image Image object
Returns:
Pixel format as described by sp_imageformat
Examples:
track.c.

int sp_image_height ( sp_image image  ) 

Get image height

Parameters:
[in] image Image object
Returns:
Height of the image (in pixels)
Examples:
track.c.

const byte* sp_image_image_id ( sp_image image  ) 

Get image ID

Parameters:
[in] image Image object
Returns:
Image ID

bool sp_image_is_loaded ( sp_image image  ) 

Check if an image is loaded. Before the image is loaded, the rest of the methods will behave as if the image is empty.

Parameters:
[in] image Image object
Returns:
True if image is loaded, false otherwise

void* sp_image_lock_pixels ( sp_image image,
int *  pitch 
)

Lock pixels and return a pointer to the pixel data.

You call sp_image_lock_pixels to obtain a pointer to the pixel buffer. Then you call sp_image_unlock_pixels() when you are done. After you have called sp_image_unlock_pixels() the pointer returned from sp_image_lock_pixels is not valid anymore, and libspotify may move the image in memory or delete it or compress it in any way it likes.

Here is a snippet from track.c:

    data = sp_image_lock_pixels(image, &pitch);

    for (y = 0; y < height; ++y) {
        byte *p = (byte *) (data + y * pitch);
        for (x = 0; x < width; ++x) {
            if (reverse) {
                bsum += *p++;
                gsum += *p++;
                rsum += *p++;
            }
            else {
                rsum += *p++;
                gsum += *p++;
                bsum += *p++;
            }
            if (alpha)
                p++;
        }
    }

    printf("Cover %d x %d %s image. Average RGB color %d, %d, %d.\n",
           width, height, format,
           rsum / width / height,
           gsum / width / height,
           bsum / width / height);

    sp_image_unlock_pixels(image);

Parameters:
[in] image Image object
[out] pitch Offset in bytes between consecutive lines in pixel data.
Returns:
Pointer to pixels.
Examples:
track.c.

void sp_image_release ( sp_image image  ) 

Decrease the reference count of an image

Parameters:
[in] image The image object
Examples:
track.c.

void sp_image_remove_load_callback ( sp_image image,
image_loaded_cb callback,
void *  userdata 
)

Remove an image load callback previously added with sp_image_add_load_callback()

Parameters:
[in] image Image object
[in] callback Callback that will not be called when image has been fetched.
[in] userdata Opaque pointer passed to callback

void sp_image_unlock_pixels ( sp_image image  ) 

Unlock pixels.

After this call it is no longer safe to assume that the pointer returned by sp_image_lock_pixels() is safe to dereference.

Parameters:
[in] image Image object
See also:
sp_image_lock_pixels
Examples:
track.c.

int sp_image_width ( sp_image image  ) 

Get image width

Parameters:
[in] image Image object
Returns:
Width of the image (in pixels)
Examples:
track.c.


Generated on Tue Apr 7 15:21:55 2009.
Copyright © 2006–2009 Spotify Ltd