## 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