Artwork

Artwork — Data structure to store iPod artwork (album covers)

Synopsis




                    Itdb_Artwork;
                    Itdb_Thumb;
enum                ItdbThumbType;
Itdb_Artwork*       itdb_artwork_new                    (void);
Itdb_Artwork*       itdb_artwork_duplicate              (Itdb_Artwork *artwork);
void                itdb_artwork_free                   (Itdb_Artwork *artwork);
gboolean            itdb_artwork_add_thumbnail          (Itdb_Artwork *artwork,
                                                         ItdbThumbType type,
                                                         const gchar *filename,
                                                         gint rotation,
                                                         GError **error);
gboolean            itdb_artwork_add_thumbnail_from_data
                                                        (Itdb_Artwork *artwork,
                                                         ItdbThumbType type,
                                                         const guchar *image_data,
                                                         gsize image_data_len,
                                                         gint rotation,
                                                         GError **error);
gboolean            itdb_artwork_add_thumbnail_from_pixbuf
                                                        (Itdb_Artwork *artwork,
                                                         ItdbThumbType type,
                                                         gpointer pixbuf,
                                                         gint rotation,
                                                         GError **error);
void                itdb_artwork_remove_thumbnail       (Itdb_Artwork *artwork,
                                                         Itdb_Thumb *thumb);
void                itdb_artwork_remove_thumbnails      (Itdb_Artwork *artwork);
Itdb_Thumb*         itdb_artwork_get_thumb_by_type      (Itdb_Artwork *artwork,
                                                         ItdbThumbType type);
gpointer            itdb_thumb_get_gdk_pixbuf           (Itdb_Device *device,
                                                         Itdb_Thumb *thumb);
Itdb_Thumb*         itdb_thumb_duplicate                (Itdb_Thumb *thumb);
void                itdb_thumb_free                     (Itdb_Thumb *thumb);
Itdb_Thumb*         itdb_thumb_new                      (void);
gchar*              itdb_thumb_get_filename             (Itdb_Device *device,
                                                         Itdb_Thumb *thumb);

Description

These functions and structures are for adding, changing, and removing album/track artwork. For working with photos, see the Photo database section.

Details

Itdb_Artwork

typedef struct {
    GList *thumbnails;     /* list of Itdb_Thumbs */
    guint32 id;            /* Artwork id used by photoalbums, starts at
			    * 0x40... libgpod will set this on sync. */
    gint32  unk028;
    guint32 rating;        /* Rating from iPhoto * 20 (PhotoDB only) */
    gint32  unk036;
    time_t  creation_date;  /* Date the image file was created
			      (creation date of image file (PhotoDB only) */
    time_t  digitized_date;/* Date the image was taken (EXIF information,
			      PhotoDB only) */
    guint32 artwork_size;  /* Size in bytes of the original source
			      image (PhotoDB only -- don't touch in
			      case of ArtworkDB!) */
    /* reserved for future use */
    gint32 reserved_int1;
    gint32 reserved_int2;
    gpointer reserved1;
    gpointer reserved2;
    /* below is for use by application */
    guint64 usertype;
    gpointer userdata;
    /* functions called to duplicate/free userdata */
    ItdbUserDataDuplicateFunc userdata_duplicate;
    ItdbUserDataDestroyFunc userdata_destroy;
} Itdb_Artwork;


Itdb_Thumb

typedef struct {
    ItdbThumbType type;
    gchar   *filename;
    guchar  *image_data;      /* holds the thumbnail data of
				 non-transfered thumbnails when
				 filename == NULL */
    gsize   image_data_len;   /* length of data */
    gpointer pixbuf;
    gint    rotation;         /* angle (0, 90, 180, 270) to rotate the image */
    guint32 offset;
    guint32 size;
    gint16  width;
    gint16  height;
    gint16  horizontal_padding;
    gint16  vertical_padding;
    /* reserved for future use */
    gint32 reserved_int1;
    gint32 reserved_int2;
    gpointer reserved1;
    gpointer reserved2;
} Itdb_Thumb;


enum ItdbThumbType

typedef enum { 
    ITDB_THUMB_COVER_SMALL = 0,
    ITDB_THUMB_COVER_LARGE,
    ITDB_THUMB_PHOTO_SMALL,
    ITDB_THUMB_PHOTO_LARGE,
    ITDB_THUMB_PHOTO_FULL_SCREEN,
    ITDB_THUMB_PHOTO_TV_SCREEN,
    ITDB_THUMB_COVER_XLARGE,      /* iPhone: cover flow */
    ITDB_THUMB_COVER_MEDIUM,      /* iPhone: cover view */
    ITDB_THUMB_COVER_SMEDIUM,     /* iPhone: ??         */
    ITDB_THUMB_COVER_XSMALL,      /* iPhone: ??         */
} ItdbThumbType;


itdb_artwork_new ()

Itdb_Artwork*       itdb_artwork_new                    (void);

Creates a new Itdb_Artwork

Returns : a new Itdb_Artwork to be freed with itdb_artwork_free() when no longer needed

itdb_artwork_duplicate ()

Itdb_Artwork*       itdb_artwork_duplicate              (Itdb_Artwork *artwork);

Duplicates artwork

artwork : an Itdb_Artwork
Returns : a new copy of artwork

itdb_artwork_free ()

void                itdb_artwork_free                   (Itdb_Artwork *artwork);

Frees memory used by artwork

artwork : an Itdb_Artwork

itdb_artwork_add_thumbnail ()

gboolean            itdb_artwork_add_thumbnail          (Itdb_Artwork *artwork,
                                                         ItdbThumbType type,
                                                         const gchar *filename,
                                                         gint rotation,
                                                         GError **error);

Appends a thumbnail of type type to existing thumbnails in artwork. No data is read from filename yet, the file will be when artwork is saved to disk. filename must still exist when that happens.

For the rotation angle you can also use the gdk constants GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND ..._CLOCKWISE.

artwork : an Itdb_Thumbnail
type : thumbnail size
filename : image file to use to create the thumbnail
rotation : angle by which the image should be rotated counterclockwise. Valid values are 0, 90, 180 and 270.
error : return location for a GError or NULL
Returns : TRUE if the thumbnail could be successfully added, FALSE otherwise. error is set appropriately.

itdb_artwork_add_thumbnail_from_data ()

gboolean            itdb_artwork_add_thumbnail_from_data
                                                        (Itdb_Artwork *artwork,
                                                         ItdbThumbType type,
                                                         const guchar *image_data,
                                                         gsize image_data_len,
                                                         gint rotation,
                                                         GError **error);

Appends a thumbnail of type type to existing thumbnails in artwork. No data is processed yet. This will be done when artwork is saved to disk.

For the rotation angle you can also use the gdk constants GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND ..._CLOCKWISE.

artwork : an Itdb_Thumbnail
type : thumbnail size
image_data : data used to create the thumbnail (the raw contents of an image file)
image_data_len : length of above data block
rotation : angle by which the image should be rotated counterclockwise. Valid values are 0, 90, 180 and 270.
error : return location for a GError or NULL
Returns : TRUE if the thumbnail could be successfully added, FALSE otherwise. error is set appropriately.

itdb_artwork_add_thumbnail_from_pixbuf ()

gboolean            itdb_artwork_add_thumbnail_from_pixbuf
                                                        (Itdb_Artwork *artwork,
                                                         ItdbThumbType type,
                                                         gpointer pixbuf,
                                                         gint rotation,
                                                         GError **error);

Appends a thumbnail of type type to existing thumbnails in artwork. No data is generated from pixbuf yet, it will be done when artwork is saved to disk. pixbuf is ref'ed by this function, but is not copied, so it should not be modified before the database is saved.

For the rotation angle you can also use the gdk constants GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND ..._CLOCKWISE.

artwork : an Itdb_Thumbnail
type : thumbnail size
pixbuf : GdkPixbuf to use to create the thumbnail
rotation : angle by which the image should be rotated counterclockwise. Valid values are 0, 90, 180 and 270.
error : return location for a GError or NULL
Returns : TRUE if the thumbnail could be successfully added, FALSE otherwise. error is set appropriately.

itdb_artwork_remove_thumbnail ()

void                itdb_artwork_remove_thumbnail       (Itdb_Artwork *artwork,
                                                         Itdb_Thumb *thumb);

Removes thumb from artwork. The memory used by thumb is freed.

artwork : an Itdb_Artwork
thumb : an Itdb_Thumb

itdb_artwork_remove_thumbnails ()

void                itdb_artwork_remove_thumbnails      (Itdb_Artwork *artwork);

Removes all thumbnails from artwork

artwork : an Itdb_Artwork

itdb_artwork_get_thumb_by_type ()

Itdb_Thumb*         itdb_artwork_get_thumb_by_type      (Itdb_Artwork *artwork,
                                                         ItdbThumbType type);

Searches artwork for an Itdb_Thumb of type type.

artwork : an Itdb_Artwork
type : type of the Itdb_Thumb to retrieve
Returns : an Itdb_Thumb of type type, or NULL if such a thumbnail couldn't be found

itdb_thumb_get_gdk_pixbuf ()

gpointer            itdb_thumb_get_gdk_pixbuf           (Itdb_Device *device,
                                                         Itdb_Thumb *thumb);

Converts thumb to a GdkPixbuf. Since we want to have gdk-pixbuf dependency optional, a generic gpointer is returned which you have to cast to a GdkPixbuf using GDK_PIXBUF() yourself.

device : an Itdb_Device
thumb : an Itdb_Thumb
Returns : a GdkPixbuf that must be unreffed with gdk_pixbuf_unref() after use, or NULL if the creation of the gdk-pixbuf failed or if libgpod was compiled without gdk-pixbuf support.

itdb_thumb_duplicate ()

Itdb_Thumb*         itdb_thumb_duplicate                (Itdb_Thumb *thumb);

Duplicates the data contained in thumb

thumb : an Itdb_Thumb
Returns : a newly allocated copy of thumb to be freed with itdb_thumb_free() after use

itdb_thumb_free ()

void                itdb_thumb_free                     (Itdb_Thumb *thumb);

Frees the memory used by thumb

thumb : an Itdb_Thumb

itdb_thumb_new ()

Itdb_Thumb*         itdb_thumb_new                      (void);

Creates a new Itdb_Thumb

Returns : newly allocated Itdb_Thumb to be freed with itdb_thumb_free() after use

itdb_thumb_get_filename ()

gchar*              itdb_thumb_get_filename             (Itdb_Device *device,
                                                         Itdb_Thumb *thumb);

Get filename of thumbnail. If it's a thumbnail on the iPod, return the full path to the ithmb file. Otherwise return the full path to the original file.

device : an Itdb_Device
thumb : an Itdb_Thumb
Returns : newly allocated string containing the absolute path to the thumbnail file.

See Also

Photo database