Cleanup: Typos in comments (to to)
[blender.git] / source / blender / imbuf / IMB_imbuf_types.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) 2001-2002 by NaN Holding BV.
17  * All rights reserved.
18  */
19
20 #ifndef __IMB_IMBUF_TYPES_H__
21 #define __IMB_IMBUF_TYPES_H__
22
23 #include "DNA_vec_types.h"  /* for rcti */
24
25 /**
26  * \file IMB_imbuf_types.h
27  * \ingroup imbuf
28  * \brief Contains defines and structs used throughout the imbuf module.
29  * \todo Clean up includes.
30  *
31  * Types needed for using the image buffer.
32  *
33  * Imbuf is external code, slightly adapted to live in the Blender
34  * context. It requires an external jpeg module, and the avi-module
35  * (also external code) in order to function correctly.
36  *
37  * This file contains types and some constants that go with them. Most
38  * are self-explanatory (e.g. IS_amiga tests whether the buffer
39  * contains an Amiga-format file).
40  */
41
42 #define IMB_MIPMAP_LEVELS       20
43 #define IMB_FILENAME_SIZE       1024
44
45 typedef struct DDSData {
46         /** DDS fourcc info */
47         unsigned int fourcc;
48         /** The number of mipmaps in the dds file */
49         unsigned int nummipmaps;
50         /** The compressed image data */
51         unsigned char *data;
52         /** The size of the compressed data */
53         unsigned int size;
54 } DDSData;
55
56 /**
57  * \ingroup imbuf
58  * This is the abstraction of an image.  ImBuf is the basic type used for all
59  * imbuf operations.
60  *
61  * Also; add new variables to the end to save pain!
62  */
63
64
65 /* Warning: Keep explicit value assignments here,
66  * this file is included in areas where not all format defines are set
67  * (e.g. intern/dds only get WITH_DDS, even if TIFF, HDR etc are also defined).
68  * See T46524. */
69
70 /** #ImBuf.ftype flag, main image types. */
71 enum eImbTypes {
72         IMB_FTYPE_PNG       = 1,
73         IMB_FTYPE_TGA       = 2,
74         IMB_FTYPE_JPG       = 3,
75         IMB_FTYPE_BMP       = 4,
76         IMB_FTYPE_OPENEXR   = 5,
77         IMB_FTYPE_IMAGIC    = 6,
78 #ifdef WITH_OPENIMAGEIO
79         IMB_FTYPE_PSD       = 7,
80 #endif
81 #ifdef WITH_OPENJPEG
82         IMB_FTYPE_JP2       = 8,
83 #endif
84 #ifdef WITH_HDR
85         IMB_FTYPE_RADHDR    = 9,
86 #endif
87 #ifdef WITH_TIFF
88         IMB_FTYPE_TIF       = 10,
89 #endif
90 #ifdef WITH_CINEON
91         IMB_FTYPE_CINEON    = 11,
92         IMB_FTYPE_DPX       = 12,
93 #endif
94
95 #ifdef WITH_DDS
96         IMB_FTYPE_DDS       = 13,
97 #endif
98 };
99
100 /* ibuf->foptions flag, type specific options.
101  * Some formats include compression rations on some bits */
102
103 #define OPENEXR_HALF    (1 << 8 )
104 /* careful changing this, it's used in DNA as well */
105 #define OPENEXR_COMPRESS (15)
106
107 #ifdef WITH_CINEON
108 #define CINEON_LOG              (1 << 8)
109 #define CINEON_16BIT    (1 << 7)
110 #define CINEON_12BIT    (1 << 6)
111 #define CINEON_10BIT    (1 << 5)
112 #endif
113
114 #ifdef WITH_OPENJPEG
115 #define JP2_12BIT               (1 << 9)
116 #define JP2_16BIT               (1 << 8)
117 #define JP2_YCC                 (1 << 7)
118 #define JP2_CINE                (1 << 6)
119 #define JP2_CINE_48FPS  (1 << 5)
120 #define JP2_JP2 (1 << 4)
121 #define JP2_J2K (1 << 3)
122 #endif
123
124 #define PNG_16BIT                       (1 << 10)
125
126 #define RAWTGA          1
127
128 #ifdef WITH_TIFF
129 #define TIF_16BIT                       (1 << 8)
130 #define TIF_COMPRESS_NONE               (1 << 7)
131 #define TIF_COMPRESS_DEFLATE            (1 << 6)
132 #define TIF_COMPRESS_LZW                (1 << 5)
133 #define TIF_COMPRESS_PACKBITS           (1 << 4)
134 #endif
135
136 typedef struct ImbFormatOptions {
137         short flag;
138         /** quality serves dual purpose as quality number for jpeg or compression amount for png */
139         char quality;
140 } ImbFormatOptions;
141
142 typedef struct ImBuf {
143         struct ImBuf *next, *prev;      /**< allow lists of ImBufs, for caches or flipbooks */
144
145         /* dimensions */
146         /** Width and Height of our image buffer.
147          * Should be 'unsigned int' since most formats use this.
148          * but this is problematic with texture math in imagetexture.c
149          * avoid problems and use int. - campbell */
150         int x, y;
151
152         /** Active amount of bits/bitplanes */
153         unsigned char planes;
154         /** Number of channels in `rect_float` (0 = 4 channel default) */
155         int channels;
156
157         /* flags */
158         /** Controls which components should exist. */
159         int     flags;
160         /** what is malloced internal, and can be freed */
161         int     mall;
162
163         /* pixels */
164
165         /** Image pixel buffer (8bit representation):
166          * - color space defaults to `sRGB`.
167          * - alpha defaults to 'straight'.
168          */
169         unsigned int *rect;
170         /** Image pixel buffer (float representation):
171          * - color space defaults to 'linear' (`rec709`).
172          * - alpha defaults to 'premul'.
173          * \note May need gamma correction to `sRGB` when generating 8bit representations.
174          * \note Formats that support higher more than 8 but channels load as floats.
175          */
176         float *rect_float;
177
178         /* resolution - pixels per meter */
179         double ppm[2];
180
181         /* tiled pixel storage */
182         int tilex, tiley;
183         int xtiles, ytiles;
184         unsigned int **tiles;
185
186         /* zbuffer */
187         /** z buffer data, original zbuffer */
188         int     *zbuf;
189         /** z buffer data, camera coordinates */
190         float *zbuf_float;
191
192         /* parameters used by conversion between byte and float */
193         /** random dither value, for conversion from float -> byte rect */
194         float dither;
195
196         /* mipmapping */
197         /** MipMap levels, a series of halved images */
198         struct ImBuf *mipmap[IMB_MIPMAP_LEVELS];
199         int miptot, miplevel;
200
201         /* externally used data */
202         /** reference index for ImBuf lists */
203         int index;
204         /** used to set imbuf to dirty and other stuff */
205         int     userflags;
206         /** image metadata */
207         struct IDProperty *metadata;
208         /** temporary storage */
209         void *userdata;
210
211         /* file information */
212         /** file type we are going to save as */
213         enum eImbTypes  ftype;
214         /** file format specific flags */
215         ImbFormatOptions foptions;
216         /** filename associated with this image */
217         char name[IMB_FILENAME_SIZE];
218         /** full filename used for reading from cache */
219         char cachename[IMB_FILENAME_SIZE];
220
221         /* memory cache limiter */
222         /** handle for cache limiter */
223         struct MEM_CacheLimiterHandle_s *c_handle;
224         /** reference counter for multiple users */
225         int refcounter;
226
227         /* some parameters to pass along for packing images */
228         /** Compressed image only used with png currently */
229         unsigned char *encodedbuffer;
230         /** Size of data written to encodedbuffer */
231         unsigned int   encodedsize;
232         /** Size of encodedbuffer */
233         unsigned int   encodedbuffersize;
234
235         /* color management */
236         /** color space of byte buffer */
237         struct ColorSpace *rect_colorspace;
238         /** color space of float buffer, used by sequencer only */
239         struct ColorSpace *float_colorspace;
240         /** array of per-display display buffers dirty flags */
241         unsigned int *display_buffer_flags;
242         /** cache used by color management */
243         struct ColormanageCache *colormanage_cache;
244         int colormanage_flag;
245         rcti invalid_rect;
246
247         /* information for compressed textures */
248         struct DDSData dds_data;
249 } ImBuf;
250
251 /**
252  * \brief userflags: Flags used internally by blender for imagebuffers
253  */
254
255 enum {
256         /** image needs to be saved is not the same as filename */
257         IB_BITMAPDIRTY =          (1 << 1),
258         /** image mipmaps are invalid, need recreate */
259         IB_MIPMAP_INVALID =       (1 << 2),
260         /** float buffer changed, needs recreation of byte rect */
261         IB_RECT_INVALID =         (1 << 3),
262         /** either float or byte buffer changed, need to re-calculate display buffers */
263         IB_DISPLAY_BUFFER_INVALID =   (1 << 4),
264         /** image buffer is persistent in the memory and should never be removed from the cache */
265         IB_PERSISTENT =               (1 << 5),
266 };
267
268 /**
269  * \name Imbuf Component flags
270  * \brief These flags determine the components of an ImBuf struct.
271  *
272  * \{ */
273
274 enum {
275         IB_rect             = 1 << 0,
276         IB_test             = 1 << 1,
277         IB_zbuf             = 1 << 3,
278         IB_mem              = 1 << 4,
279         IB_rectfloat        = 1 << 5,
280         IB_zbuffloat        = 1 << 6,
281         IB_multilayer       = 1 << 7,
282         IB_metadata         = 1 << 8,
283         IB_animdeinterlace  = 1 << 9,
284         IB_tiles            = 1 << 10,
285         IB_tilecache        = 1 << 11,
286         /** indicates whether image on disk have premul alpha */
287         IB_alphamode_premul = 1 << 12,
288         /** if this flag is set, alpha mode would be guessed from file */
289         IB_alphamode_detect = 1 << 13,
290         /** ignore alpha on load and substitute it with 1.0f */
291         IB_ignore_alpha     = 1 << 14,
292         IB_thumbnail        = 1 << 15,
293         IB_multiview        = 1 << 16,
294 };
295
296 /** \} */
297
298 /**
299  * \name Imbuf preset profile tags
300  * \brief Some predefined color space profiles that 8 bit imbufs can represent
301  *
302  * \{ */
303 #define IB_PROFILE_NONE                 0
304 #define IB_PROFILE_LINEAR_RGB   1
305 #define IB_PROFILE_SRGB                 2
306 #define IB_PROFILE_CUSTOM               3
307
308 /** \} */
309
310 /* dds */
311 #ifdef WITH_DDS
312 #ifndef DDS_MAKEFOURCC
313 #define DDS_MAKEFOURCC(ch0, ch1, ch2, ch3)\
314         ((unsigned long)(unsigned char)(ch0) | \
315         ((unsigned long)(unsigned char)(ch1) << 8) | \
316         ((unsigned long)(unsigned char)(ch2) << 16) | \
317         ((unsigned long)(unsigned char)(ch3) << 24))
318 #endif  /* DDS_MAKEFOURCC */
319
320 /*
321  * FOURCC codes for DX compressed-texture pixel formats
322  */
323
324 #define FOURCC_DDS   (DDS_MAKEFOURCC('D','D','S',' '))
325 #define FOURCC_DXT1  (DDS_MAKEFOURCC('D','X','T','1'))
326 #define FOURCC_DXT2  (DDS_MAKEFOURCC('D','X','T','2'))
327 #define FOURCC_DXT3  (DDS_MAKEFOURCC('D','X','T','3'))
328 #define FOURCC_DXT4  (DDS_MAKEFOURCC('D','X','T','4'))
329 #define FOURCC_DXT5  (DDS_MAKEFOURCC('D','X','T','5'))
330
331 #endif  /* DDS */
332 extern const char *imb_ext_image[];
333 extern const char *imb_ext_movie[];
334 extern const char *imb_ext_audio[];
335
336 /* image formats that can only be loaded via filepath */
337 extern const char *imb_ext_image_filepath_only[];
338
339 /**
340  * \name Imbuf Color Management Flag
341  * \brief Used with #ImBuf.colormanage_flag
342  *
343  * \{ */
344
345 enum {
346         IMB_COLORMANAGE_IS_DATA = (1 << 0),
347 };
348
349 /** \} */
350
351 #endif  /* __IMB_IMBUF_TYPES_H__ */