Artwork

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

Synopsis




                    Itdb_Artwork;
Itdb_Artwork*       itdb_artwork_new                    (void);
Itdb_Artwork*       itdb_artwork_duplicate              (Itdb_Artwork *artwork);
void                itdb_artwork_free                   (Itdb_Artwork *artwork);
gpointer            itdb_artwork_get_pixbuf             (Itdb_Device *device,
                                                         Itdb_Artwork *artwork,
                                                         gint width,
                                                         gint height);
gboolean            itdb_artwork_set_thumbnail          (Itdb_Artwork *artwork,
                                                         const gchar *filename,
                                                         gint rotation,
                                                         GError **error);
gboolean            itdb_artwork_set_thumbnail_from_data
                                                        (Itdb_Artwork *artwork,
                                                         const guchar *image_data,
                                                         gsize image_data_len,
                                                         gint rotation,
                                                         GError **error);
gboolean            itdb_artwork_set_thumbnail_from_pixbuf
                                                        (Itdb_Artwork *artwork,
                                                         gpointer pixbuf,
                                                         gint rotation,
                                                         GError **error);
void                itdb_artwork_remove_thumbnails      (Itdb_Artwork *artwork);
                    Itdb_Thumb;
Itdb_Thumb*         itdb_thumb_duplicate                (Itdb_Thumb *thumb);
void                itdb_thumb_free                     (Itdb_Thumb *thumb);
gpointer            itdb_thumb_to_pixbuf_at_size        (Itdb_Device *device,
                                                         Itdb_Thumb *thumb,
                                                         gint width,
                                                         gint height);
GList*              itdb_thumb_to_pixbufs               (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 {
    Itdb_Thumb *thumbnail;
    guint32 id;
    guint64 dbid;
    gint32  unk028;
    guint32 rating;
    gint32  unk036;
    time_t  creation_date;
    time_t  digitized_date;
    guint32 artwork_size;
    /* 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;

Structure representing artwork in an Itdb_iTunesDB or Itdb_PhotoDB

Itdb_Thumb *thumbnail;

 An Itdb_Thumb

guint32 id;

 Artwork id used by photoalbums. This starts at 0x40 and is set automatically when the ArtworkDB or PhotoDB is written

guint64 dbid;

 The dbid of associated track. Used internally by libgpod.

gint32 unk028;

 Unknown

guint32 rating;

 Rating from iPhoto * 20 (PhotoDB only)

gint32 unk036;

 Unknown

time_t creation_date;

 Date the image file was created (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!)

gint32 reserved_int1;

 Reserved for future use

gint32 reserved_int2;

 Reserved for future use

gpointer reserved1;

 Reserved for future use

gpointer reserved2;

 Reserved for future use

guint64 usertype;

 For use by application

gpointer userdata;

 For use by application

ItdbUserDataDuplicateFunc userdata_duplicate;

 A function to duplicate userdata

ItdbUserDataDestroyFunc userdata_destroy;

 A function to free userdata

Since 0.3.0

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

Since 0.3.0

itdb_artwork_duplicate ()

Itdb_Artwork*       itdb_artwork_duplicate              (Itdb_Artwork *artwork);

Duplicates artwork

artwork :

 an Itdb_Artwork

Returns :

 a new copy of artwork

Since 0.3.0

itdb_artwork_free ()

void                itdb_artwork_free                   (Itdb_Artwork *artwork);

Frees memory used by artwork

artwork :

 an Itdb_Artwork

Since 0.3.0

itdb_artwork_get_pixbuf ()

gpointer            itdb_artwork_get_pixbuf             (Itdb_Device *device,
                                                         Itdb_Artwork *artwork,
                                                         gint width,
                                                         gint height);

Returns a GdkPixbuf representing the thumbnail stored in artwork scaling it if appropriate. If either height or width is -1, then the biggest unscaled thumbnail available will be returned

device :

 an Itdb_Device

artwork :

 an Itdb_Artwork

width :

 width of the pixbuf to retrieve, -1 for the biggest possible size and 0 for the smallest possible size (with no scaling)

height :

 height of the pixbuf to retrieve, -1 for the biggest possible size and 0 for the smallest possible size (with no scaling)

Returns :

 a GdkPixbuf that must be unreffed when no longer used, NULL if no artwork could be found or if libgpod is compiled without GdkPixbuf support

Since 0.7.0

itdb_artwork_set_thumbnail ()

gboolean            itdb_artwork_set_thumbnail          (Itdb_Artwork *artwork,
                                                         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, GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE, GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND GDK_PIXBUF_ROTATE_CLOCKWISE.

artwork :

 an Itdb_Artwork

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.

Since 0.7.0

itdb_artwork_set_thumbnail_from_data ()

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

Set a thumbnail 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, GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE, GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND GDK_PIXBUF_ROTATE_CLOCKWISE.

artwork :

 an Itdb_Artwork

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.

Since 0.7.0

itdb_artwork_set_thumbnail_from_pixbuf ()

gboolean            itdb_artwork_set_thumbnail_from_pixbuf
                                                        (Itdb_Artwork *artwork,
                                                         gpointer pixbuf,
                                                         gint rotation,
                                                         GError **error);

Set a thumbnail 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, GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE, GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND GDK_PIXBUF_ROTATE_CLOCKWISE.

artwork :

 an Itdb_Artwork

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.

Since 0.7.0

itdb_artwork_remove_thumbnails ()

void                itdb_artwork_remove_thumbnails      (Itdb_Artwork *artwork);

Removes all thumbnails from artwork

artwork :

 an Itdb_Artwork

Since 0.3.0

Itdb_Thumb

typedef struct {
    ItdbThumbDataType data_type;
    guint rotation;
} Itdb_Thumb;

This is an opaque structure representing a thumbnail to be transferred to the ipod or read from the ipod.

ItdbThumbDataType data_type;

 The type of data (file, memory, pixbuf, ipod, etc.)

guint rotation;

 Angle by which the image is rotated counterclockwise

Since 0.3.0

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

Since 0.3.0

itdb_thumb_free ()

void                itdb_thumb_free                     (Itdb_Thumb *thumb);

Frees the memory used by thumb

thumb :

 an Itdb_Thumb

Since 0.3.0

itdb_thumb_to_pixbuf_at_size ()

gpointer            itdb_thumb_to_pixbuf_at_size        (Itdb_Device *device,
                                                         Itdb_Thumb *thumb,
                                                         gint width,
                                                         gint height);

Converts thumb to a GdkPixbuf.

Note

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

width :

 width of the pixbuf to retrieve, -1 for the biggest possible size and 0 for the smallest possible size (with no scaling)

height :

 height of the pixbuf to retrieve, -1 for the biggest possible size and 0 for the smallest possible size (with no scaling)

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.

Since 0.7.0

itdb_thumb_to_pixbufs ()

GList*              itdb_thumb_to_pixbufs               (Itdb_Device *device,
                                                         Itdb_Thumb *thumb);

Converts thumb to a GList of GdkPixbuf. The returned GList will generally contain only 1 element, the full-size pixbuf associated with thumb, but when the artwork has been read from the ipod and hasn't been modified from the library, then the returned GList will contain several GdkPixbuf corresponding to the various thumbnail sizes that were written to the iPod database.

device :

 an Itdb_Device

thumb :

 an Itdb_Thumb

Returns :

 a GList of GdkPixbuf which are associated with thumb, NULL if the pixbuf was invalid or if libgpod is compiled without gdk-pixbuf support. The GdkPixbuf must be unreffed with gdk_pixbuf_unref() after use and the GList must be freed with g_list_free().

Since 0.7.0

See Also

Photo database