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);
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;
    guint32 creation_date; /* Date the image file was created
			      (creation date of image file (Mac type,
			      PhotoDB only) */
    guint32 digitized_date;/* Date the image was taken (EXIF
			      information, Mac type, PhotoDB only) */
    guint32 artwork_size;  /* Size in bytes of the original source
			      image (PhotoDB only -- don't touch in
			      case of ArtworkDB!) */
    /* 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 */
    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;
} Itdb_Thumb;


enum ItdbThumbType

typedef enum { 
    ITDB_THUMB_COVER_SMALL,
    ITDB_THUMB_COVER_LARGE,
    ITDB_THUMB_PHOTO_SMALL,
    ITDB_THUMB_PHOTO_LARGE,
    ITDB_THUMB_PHOTO_FULL_SCREEN,
    ITDB_THUMB_PHOTO_TV_SCREEN
} 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_remove_thumbnail ()

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

Removes thumb from artwork. The memory used by thumb isn't 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