im.im_util source code

1 /** \file
2  * \brief Utilities
3  *
4  * See Copyright Notice in im_lib.h
5  */
6 module im.im_util;
7 
8 version(IM) :
9 
10 import core.stdc.config : c_long, c_ulong;
11 import std.algorithm.comparison: min, max, clamp;
12 import std.traits;
13 import im.im : FreeEnumMembers, IM_ALPHA, IM_PACKED, IM_TOPDOWN;
14 
15 //version(DigitalMars) version(Windows) { pragma(lib, "im.lib"); } // required anyway
16 version(DigitalMars) version(Windows) { pragma(lib, "im_lzo"); }
17 
18 extern(C) :
19 
20 @nogc nothrow {
21 /** \defgroup util Utilities
22  * \par
23  * See \ref im_util.h
24  * @{
25  */
26 
27 //#define IM_MIN(_a, _b) (_a < _b? _a: _b)
28 alias IM_MIN = min;
29 //#define IM_MAX(_a, _b) (_a > _b? _a: _b)
30 alias IM_MAX = max;
31 
32 /** @} */
33 
34 
35 /** \defgroup str String Utilities
36  * \par
37  * See \ref im_util.h
38  * \ingroup util */
39 
40 /** Check if the two strings are equal.
41  * \ingroup str */
42 int imStrEqual(const(char)* str1, const(char)* str2);
43 
44 /** Calculate the size of the string but limited to max_len.
45  * \ingroup str */
46 int imStrNLen(const(char)* str, int max_len);
47 
48 /** Check if the data is a string.
49  * \ingroup str */
50 int imStrCheck(const(void)* data, int count);
51 
52 
53 
54 /** \defgroup imageutil Raw Data Utilities
55  * \par
56  * See \ref im_util.h
57  * \ingroup imagerep */
58 
59 /** Returns the size of the data buffer.
60  *
61  * \verbatim im.ImageDataSize(width: number, height: number, color_mode: number, data_type: number) -> datasize: number [in Lua 5] \endverbatim
62  * \ingroup imageutil */
63 int imImageDataSize(int width, int height, int color_mode, int data_type);
64 
65 /** Returns the size of one line of the data buffer. \n
66  * This depends if the components are packed. If packed includes all components, if not includes only one.
67  *
68  * \verbatim im.ImageLineSize(width: number, color_mode: number, data_type: number) -> linesize: number [in Lua 5] \endverbatim
69  * \ingroup imageutil */
70 int imImageLineSize(int width, int color_mode, int data_type);
71 
72 /** Returns the number of elements of one line of the data buffer. \n
73  * This depends if the components are packed. If packed includes all components, if not includes only one.
74  *
75  * \verbatim im.ImageLineCount(width: number, color_mode: number) -> linecount: number [in Lua 5] \endverbatim
76  * \ingroup imageutil */
77 int imImageLineCount(int width, int color_mode);
78 
79 /** Check if the combination color_mode+data_type is valid.
80  *
81  * \verbatim im.ImageCheckFormat(color_mode: number, data_type: number) -> check: boolean [in Lua 5] \endverbatim
82  * \ingroup imageutil */
83 int imImageCheckFormat(int color_mode, int data_type);
84 
85 
86 
87 /** \defgroup colorutl Color Utilities
88  * \par
89  * See \ref im_util.h
90  * \ingroup util */
91 
92 /** Encode RGB components in a long for palette usage. \n
93  * "long" definition is compatible with the CD library definition.
94  *
95  * \verbatim im.ColorEncode(red: number, green: number, blue: number) -> color: lightuserdata [in Lua 5] \endverbatim
96  * \ingroup colorutl */
97 c_long imColorEncode(ubyte red, ubyte green, ubyte blue);
98 
99 /** Decode RGB components from a long for palette usage. \n
100  * "long" definition is compatible with the CD library definition.
101  *
102  * \verbatim im.ColorDecode(color: lightuserdata) -> red: number, green: number, blue: number [in Lua 5] \endverbatim
103  * \ingroup colorutl */
104 void imColorDecode(ubyte* red, ubyte* green, ubyte* blue, c_long color);
105 
106 
107 
108 /** \defgroup colormodeutl Color Mode Utilities
109  * \par
110  * See \ref im_util.h
111  * \ingroup imagerep */
112 
113 /** Returns the color mode name.
114  *
115  * \verbatim im.ColorModeSpaceName(color_mode: number) -> name: string [in Lua 5] \endverbatim
116  * \ingroup colormodeutl */
117 const(char)* imColorModeSpaceName(int color_mode);
118 
119 /** Returns the number of components of the color space including alpha.
120  *
121  * \verbatim im.ColorModeDepth(color_mode: number) -> depth: number [in Lua 5] \endverbatim
122  * \ingroup colormodeutl */
123 int imColorModeDepth(int color_mode);
124 
125 /** Returns the color space of the color mode.
126  *
127  * \verbatim im.ColorModeSpace(color_mode: number) -> color_space: number [in Lua 5] \endverbatim
128  * \ingroup colormodeutl */
129 T imColorModeSpace(T)(T _cm) if (isIntegral!T) { return _cm & 0xFF;}
130 
131 /** Check if the two color modes match. Only the color space is compared.
132  *
133  * \verbatim im.ColorModeMatch(color_mode1: number, color_mode2: number) -> match: boolean [in Lua 5] \endverbatim
134  * \ingroup colormodeutl */
135 T imColorModeMatch(T)(T _cm1, T _cm2) if (isIntegral!T) { return imColorModeSpace(_cm1) == imColorModeSpace(_cm2); }
136 
137 /** Check if the color mode has an alpha channel.
138  *
139  * \verbatim im.ColorModeHasAlpha(color_mode: number) -> has_alpha: boolean [in Lua 5] \endverbatim
140  * \ingroup colormodeutl */
141 T imColorModeHasAlpha(T)(T _cm) if (isIntegral!T) { return _cm & IM_ALPHA; }
142 
143 /** Check if the color mode components are packed in one plane.
144  *
145  * \verbatim im.ColorModeIsPacked(color_mode: number) -> is_packed: boolean [in Lua 5] \endverbatim
146  * \ingroup colormodeutl */
147 T imColorModeIsPacked(T)(T _cm) if (isIntegral!T) { return _cm & IM_PACKED; }
148 
149 /** Check if the color mode orients the image from top down to bottom.
150  *
151  * \verbatim im.ColorModeIsTopDown(color_mode: number) -> is_top_down: boolean [in Lua 5] \endverbatim
152  * \ingroup colormodeutl */
153 T imColorModeIsTopDown(T)(T _cm) if (isIntegral!T) { return _cm & IM_TOPDOWN; }
154 
155 /** Returns the color space of the equivalent display bitmap image. \n
156  * Original packing and alpha are ignored. Returns IM_RGB, IM_GRAY, IM_MAP or IM_BINARY.
157  *
158  * \verbatim im.ColorModeToBitmap(color_mode: number) -> color_space: number [in Lua 5] \endverbatim
159  * \ingroup colormodeutl */
160 int imColorModeToBitmap(int color_mode);
161 
162 /** Check if the color mode and data_type defines a display bitmap image.
163  *
164  * \verbatim im.ColorModeIsBitmap(color_mode: number, data_type: number) -> is_bitmap: boolean [in Lua 5] \endverbatim
165  * \ingroup colormodeutl */
166 int imColorModeIsBitmap(int color_mode, int data_type);
167 
168 /** Max depth is 4+1  (cmyk+alpha)
169  * \ingroup colormodeutl */
170 enum IM_MAXDEPTH = 5;
171 
172 
173 
174 /** \defgroup datatypeutl Data Type Utilities
175  * \par
176  * See \ref im_util.h
177  * \ingroup util
178  * @{
179  */
180 
181 //typedef unsigned char imbyte;
182 //typedef unsigned short imushort;
183 
184 ubyte IM_BYTECROP(c_ulong _v)      pure nothrow @nogc @safe              { return cast(ubyte)clamp(_v,    0,  255); }
185 T  IM_FLOATCROP(T)(T _v)           pure nothrow @nogc @safe if (isFloatingPoint!T)  { return clamp(_v,  0.f,  1.f); }
186 T    IM_CROPMAX(T)(T _v, T _max)         pure nothrow @nogc @safe if (isNumeric!T)  { return clamp(_v,    0, _max); }
187 T IM_CROPMINMAX(T)(T _v, T _min, T _max) pure nothrow @nogc @safe if (isNumeric!T)  { return clamp(_v, _min, _max); }
188 
189 /** @} */
190 
191 /** Returns the size in bytes of a specified numeric data type.
192  *
193  * \verbatim im.DataTypeSize(data_type: number) -> size: number [in Lua 5] \endverbatim
194  * \ingroup datatypeutl */
195 int imDataTypeSize(int data_type);
196 
197 /** Returns the numeric data type name given its identifier.
198  *
199  * \verbatim im.DataTypeName(data_type: number) -> name: string [in Lua 5] \endverbatim
200  * \ingroup datatypeutl */
201 const(char)* imDataTypeName(int data_type);
202 
203 /** Returns the maximum value of an integer data type. For floating point returns 0.
204  *
205  * \verbatim im.DataTypeIntMax(data_type: number) -> int_max: number [in Lua 5] \endverbatim
206  * \ingroup datatypeutl */
207 c_ulong imDataTypeIntMax(int data_type);
208 
209 /** Returns the minimum value of an integer data type. For floating point returns 0. 
210  *
211  * \verbatim im.DataTypeIntMin(data_type: number) -> int_min: number [in Lua 5] \endverbatim
212  * \ingroup datatypeutl */
213 c_long imDataTypeIntMin(int data_type);
214 
215 } // @nogc nothrow
216 
217 
218 /** \defgroup bin Binary Data Utilities
219  * \par
220  * See \ref im_util.h
221  * \ingroup util */
222 
223 /** CPU Byte Orders. 
224   * \ingroup bin */
225 enum imByteOrder
226 {
227   IM_LITTLEENDIAN, /**< Little Endian - The most significant byte is on the right end of a word. Used by Intel processors. */
228   IM_BIGENDIAN     /**< Big Endian - The most significant byte is on the left end of a word. Used by Motorola processors, also is the network standard byte order. */
229 }
230 mixin FreeEnumMembers!imByteOrder;
231 
232 @nogc nothrow :
233 
234 /** Returns the current CPU byte order.
235  * \ingroup bin */
236 int imBinCPUByteOrder();
237 
238 /** Changes the byte order of an array of 2, 4 or 8 byte values.
239  * \ingroup bin */
240 void imBinSwapBytes(void* data, int count, int size);
241 
242 /** Changes the byte order of an array of 2 byte values.
243  * \ingroup bin */
244 void imBinSwapBytes2(void* data, int count);
245 
246 /** Inverts the byte order of the 4 byte values 
247  * \ingroup bin */
248 void imBinSwapBytes4(void* data, int count);
249             
250 /** Inverts the byte order of the 8 byte values 
251  * \ingroup bin */
252 void imBinSwapBytes8(void* data, int count);
253 
254 
255 
256 /** \defgroup compress Data Compression Utilities
257  * \par
258  * Deflate compression support uses zlib version 1.2.8.     \n
259  * http://www.zlib.org/                                     \n
260  * Copyright (C) 1995-2013 Jean-loup Gailly and Mark Adler
261  * \par
262  * LZF compression support uses libLZF version 3.5.       \n
263  * http://software.schmorp.de/pkg/liblzf                  \n
264  * Copyright (C) 2000-2009 Marc Alexander Lehmann
265  * \par
266  * LZO compression support uses mini-libLZO version 2.07. \n
267  * http://www.oberhumer.com/opensource/lzo/                  \n
268  * Copyright (C) 1996-2014 Markus Franz Xaver Johannes Oberhumer \n
269  * But its License is GPL, so we kept it in a separate library 
270  * called "im_lzo" that is also GPL.
271  *
272  * See \ref im_util.h
273  * \ingroup util */
274 
275 /** Compresses the data using the ZLIB Deflate compression. \n
276  * The destination buffer must be at least 0.1% larger than source_size plus 12 bytes. \n
277  * It compresses raw byte data. zip_quality can be 1 to 9. \n
278  * Returns the size of the compressed buffer or zero if failed.
279  * \ingroup compress */
280 int imCompressDataZ(const(void)* src_data, int src_size, void* dst_data, int dst_size, int zip_quality);
281 
282 /** Uncompresses the data compressed with the ZLIB Deflate compression. \n
283  * Returns zero if failed.
284  * \ingroup compress */
285 int imCompressDataUnZ(const(void)* src_data, int src_size, void* dst_data, int dst_size);
286 
287 /** Compresses the data using the libLZF compression. \n
288  * Returns the size of the compressed buffer or zero if failed.
289  * \ingroup compress */
290 int imCompressDataLZF(const(void)* src_data, int src_size, void* dst_data, int dst_size);
291 
292 /** Uncompresses the data compressed with the libLZF compression. \n
293  * Returns zero if failed.
294  * \ingroup compress */
295 int imCompressDataUnLZF(const(void)* src_data, int src_size, void* dst_data, int dst_size);
296 
297 /** Compresses the data using the libLZO compression. (Since 3.9) \n
298 * Returns the size of the compressed buffer or zero if failed. \n
299 * Available in a separate library called "im_lzo" which license is GPL.
300 * \ingroup compress */
301 int imCompressDataLZO(const(void)* src_data, int src_size, void* dst_data, int dst_size);
302 
303 /** Uncompresses the data compressed with the libLZO compression. (Since 3.9) \n
304 * Returns zero if failed. \n
305 * Available in a separate library called "im_lzo" which license is GPL.
306 * \ingroup compress */
307 int imCompressDataUnLZO(const(void)* src_data, int src_size, void* dst_data, int dst_size);