Cleanup: remove redundant doxygen \file argument
[blender.git] / source / blender / blenkernel / BKE_icons.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  *
16  * The Original Code is Copyright (C) 2006-2007 Blender Foundation.
17  * All rights reserved.
18  */
19
20 #ifndef __BKE_ICONS_H__
21 #define __BKE_ICONS_H__
22
23 /** \file \ingroup bke
24  *
25  * Resizable Icons for Blender
26  */
27
28 typedef void (*DrawInfoFreeFP)(void *drawinfo);
29
30 enum {
31         /** ID preview: obj is #ID. */
32         ICON_DATA_ID = 0,
33         /** Preview: obj is #PreviewImage */
34         ICON_DATA_PREVIEW,
35         /** 2D triangles: obj is #Icon_Geom */
36         ICON_DATA_GEOM,
37         /** Studiolight */
38         ICON_DATA_STUDIOLIGHT,
39         /** GPencil Layer color preview (annotations): obj is #bGPDlayer */
40         ICON_DATA_GPLAYER,
41 };
42
43 struct Icon {
44         void *drawinfo;
45         /**
46          * Data defined by #obj_type
47          * \note for #ICON_DATA_GEOM the memory is owned by the icon,
48          * could be made into a flag if we want that to be optional.
49          */
50         void *obj;
51         char  obj_type;
52         /** Internal use only. */
53         char flag;
54         /** #ID_Type or 0 when not used for ID preview. */
55         short id_type;
56         DrawInfoFreeFP drawinfo_free;
57 };
58
59 /** Used for #ICON_DATA_GEOM, assigned to #Icon.obj. */
60 struct Icon_Geom {
61         int icon_id;
62         int coords_len;
63         int coords_range[2];
64         const unsigned char (*coords)[2];
65         const unsigned char (*colors)[4];
66         /* when not NULL, the memory of coords and colors is a sub-region of this pointer. */
67         const void *mem;
68 };
69
70 typedef struct Icon Icon;
71
72 struct ID;
73 struct ImBuf;
74 struct PreviewImage;
75 struct StudioLight;
76 struct bGPDlayer;
77
78 enum eIconSizes;
79
80 void BKE_icons_init(int first_dyn_id);
81
82 /* return icon id for library object or create new icon if not found */
83 int BKE_icon_id_ensure(struct ID *id);
84
85 /* return icon id for Grease Pencil layer (color preview) or create new icon if not found */
86 int BKE_icon_gplayer_color_ensure(struct bGPDlayer *gpl);
87
88 int BKE_icon_preview_ensure(struct ID *id, struct PreviewImage *preview);
89
90 /* retrieve icon for id */
91 struct Icon *BKE_icon_get(const int icon_id);
92
93 /* set icon for id if not already defined */
94 /* used for inserting the internal icons */
95 void BKE_icon_set(const int icon_id, struct Icon *icon);
96
97 /* remove icon and free data if library object becomes invalid */
98 void BKE_icon_id_delete(struct ID *id);
99
100 bool BKE_icon_delete(const int icon_id);
101 bool BKE_icon_delete_unmanaged(const int icon_id);
102
103 /* report changes - icon needs to be recalculated */
104 void BKE_icon_changed(const int icon_id);
105
106 /* free all icons */
107 void BKE_icons_free(void);
108
109 /* free all icons marked for deferred deletion */
110 void BKE_icons_deferred_free(void);
111
112 /* free the preview image for use in list */
113 void BKE_previewimg_freefunc(void *link);
114
115 /* free the preview image */
116 void BKE_previewimg_free(struct PreviewImage **prv);
117
118 /* clear the preview image or icon, but does not free it */
119 void BKE_previewimg_clear(struct PreviewImage *prv);
120
121 /* clear the preview image or icon at a specific size */
122 void BKE_previewimg_clear_single(struct PreviewImage *prv, enum eIconSizes size);
123
124 /* get the preview from any pointer */
125 struct PreviewImage **BKE_previewimg_id_get_p(const struct ID *id);
126
127 /* free the preview image belonging to the id */
128 void BKE_previewimg_id_free(struct ID *id);
129
130 /* create a new preview image */
131 struct PreviewImage *BKE_previewimg_create(void);
132
133 /* create a copy of the preview image */
134 struct PreviewImage *BKE_previewimg_copy(const struct PreviewImage *prv);
135
136 void BKE_previewimg_id_copy(struct ID *new_id, const struct ID *old_id);
137
138 /* retrieve existing or create new preview image */
139 struct PreviewImage *BKE_previewimg_id_ensure(struct ID *id);
140
141 void BKE_previewimg_ensure(struct PreviewImage *prv, const int size);
142
143 struct PreviewImage *BKE_previewimg_cached_get(const char *name);
144
145 struct PreviewImage *BKE_previewimg_cached_ensure(const char *name);
146
147 struct PreviewImage *BKE_previewimg_cached_thumbnail_read(
148         const char *name, const char *path, const int source, bool force_update);
149
150 void BKE_previewimg_cached_release(const char *name);
151 void BKE_previewimg_cached_release_pointer(struct PreviewImage *prv);
152
153 int BKE_icon_geom_ensure(struct Icon_Geom *geom);
154 struct Icon_Geom *BKE_icon_geom_from_memory(const uchar *data, size_t data_len);
155 struct Icon_Geom *BKE_icon_geom_from_file(const char *filename);
156
157 struct ImBuf *BKE_icon_geom_rasterize(
158         const struct Icon_Geom *geom,
159         const unsigned int size_x, const unsigned int size_y);
160
161 int BKE_icon_ensure_studio_light(struct StudioLight *sl, int id_type);
162
163 #define ICON_RENDER_DEFAULT_HEIGHT 32
164
165 #endif /*  __BKE_ICONS_H__ */