Artwork

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