im.im_convert source code

1 /** \file
2  * \brief Image Conversion
3  *
4  * See Copyright Notice in im_lib.h
5  */
6 module im.im_convert;
7 
8 version(IM) :
9 
10 import core.stdc.config : c_long;
11 import im.im_image;
12 import im.im : FreeEnumMembers;
13 
14 //version(DigitalMars) version(Windows) { pragma(lib, "im.lib"); } // required anyway
15 
16 extern(C) :
17 
18 
19 /** \defgroup convert Image Conversion
20  * \par
21  * Converts one type of image into another. Can convert between color modes
22  * and between data types.
23  * \par
24  * See \ref im_convert.h
25  * \ingroup imgclass */
26 
27 
28 /** Complex to real conversions
29  * \ingroup convert */
30 enum imComplex2Real 
31 {
32   IM_CPX_REAL, 
33   IM_CPX_IMAG, 
34   IM_CPX_MAG, 
35   IM_CPX_PHASE
36 }
37 mixin FreeEnumMembers!imComplex2Real;
38 
39 
40 /** Predefined Gamma factors. Gamma can be any real number.
41  * When gamma<0 use logarithmic, when gamma>0 use exponential.
42  * gamma(x,g) = ((e^(g*x))-1)/(exp(g)-1)
43  * gamma(x,g) = (log((g*x)+1))/(log(g+1))
44  * \ingroup convert */
45 enum imGammaFactor
46 {
47   IM_GAMMA_LINEAR   = 0,
48   IM_GAMMA_LOGLITE  = -10,
49   IM_GAMMA_LOGHEAVY = -1000,
50   IM_GAMMA_EXPLITE  = 2,
51   IM_GAMMA_EXPHEAVY = 7
52 }
53 mixin FreeEnumMembers!imGammaFactor;
54 
55 /** Predefined Cast Modes \n
56  * See also \ref color Color Manipulation, Color Component Intervals section.
57  * \ingroup convert */
58 enum imCastMode
59 {
60   IM_CAST_MINMAX, /**< scan for min and max values.  */
61   IM_CAST_FIXED,  /**< use predefined min-max values. */
62   IM_CAST_DIRECT, /**< direct type cast the value.   */
63   IM_CAST_USER    /**< user attributes called "UserMin" and "UserMax", both float values. */
64 }
65 mixin FreeEnumMembers!imCastMode;
66 
67 @nogc nothrow :
68 
69 /** Changes the image data type, using a complex2real conversion, 
70  * a gamma factor, and an absolute mode (modulus). \n
71  * When demoting the data type the function will scan source for min/max values or use fixed values (cast_mode)
72  * to scale the result according to the target range. \n
73  * Except complex to real that will use only the complex2real conversion. \n
74  * Images must be of the same size and color mode. If data type is the same nothing is done. \n
75  * Returns IM_ERR_NONE, IM_ERR_DATA or IM_ERR_COUNTER, see also \ref imErrorCodes. \n
76  * See also \ref imDataType, \ref datatypeutl, \ref imComplex2Real, \ref imGammaFactor and \ref imCastMode.
77  *
78  * \verbatim im.ConvertDataType(src_image: imImage, dst_image: imImage, cpx2real: number, gamma: number, absolute: boolean, cast_mode: number) -> error: number [in Lua 5] \endverbatim
79  * \verbatim im.ConvertDataTypeNew(image: imImage, data_type: number, cpx2real: number, gamma: number, absolute: boolean, cast_mode: number) -> error: number, new_image: imImage  [in Lua 5] \endverbatim
80  * \ingroup convert */
81 int imConvertDataType(const(imImage)* src_image, imImage* dst_image, int cpx2real, float gamma, int absolute, int cast_mode);
82 
83 /** Converts one color space to another. \n
84  * Images must be of the same size and data type. If color mode is the same nothing is done. \n
85  * CMYK can be converted to RGB only, and it is a very simple conversion. \n
86  * All colors can be converted to Binary, the non zero gray values are converted to 1. \n
87  * RGB to Map uses the median cut implementation from the free IJG JPEG software, copyright Thomas G. Lane. \n
88  * Alpha channel is considered and Transparency* attributes are converted to alpha channel. \n
89  * All other color space conversions assume sRGB and CIE definitions, see \ref color. \n
90  * Returns IM_ERR_NONE, IM_ERR_DATA or IM_ERR_COUNTER, see also \ref imErrorCodes. \n
91  * See also \ref imColorSpace, \ref imColorModeConfig and \ref colormodeutl. 
92  *
93  * \verbatim im.ConvertColorSpace(src_image: imImage, dst_image: imImage) -> error: number [in Lua 5] \endverbatim
94  * \verbatim im.ConvertColorSpaceNew(image: imImage, color_space: number, has_alpha: boolean) -> error: number, new_image: imImage [in Lua 5] \endverbatim
95  * \ingroup convert */
96 int imConvertColorSpace(const(imImage)* src_image, imImage* dst_image);
97 
98 /** Converts the image to its bitmap equivalent, 
99  * uses \ref imConvertColorSpace and \ref imConvertDataType. \n
100  * Returns IM_ERR_NONE, IM_ERR_DATA or IM_ERR_COUNTER, see also \ref imErrorCodes.
101  * See also \ref imImageIsBitmap, \ref imComplex2Real, \ref imGammaFactor and \ref imCastMode. \n
102  * The function im.ConvertToBitmapNew uses the default conversion result from \ref imColorModeToBitmap if color_space is nil.
103  *
104  * \verbatim im.ConvertToBitmap(src_image: imImage, dst_image: imImage, cpx2real: number, gamma: number, absolute: boolean, cast_mode: number) -> error: number [in Lua 5] \endverbatim
105  * \verbatim im.ConvertToBitmapNew(image: imImage, color_space: number, has_alpha: boolean, cpx2real: number, gamma: number, absolute: boolean, cast_mode: number) -> error: number, new_image: imImage [in Lua 5] \endverbatim
106  * \ingroup convert */
107 int imConvertToBitmap(const(imImage)* src_image, imImage* dst_image, int cpx2real, float gamma, int absolute, int cast_mode);
108 
109 /** Returns an OpenGL compatible data buffer. Also returns the correspondent pixel format. \n
110  * The memory allocated is stored in the attribute "GLDATA" with BYTE type. And it will exists while the image exists. \n
111  * It can be cleared by setting the attribute to NULL. \n
112  * MAP images are converted to RGB, and BINARY images are converted to GRAY.
113  * Alpha channel is considered and Transparency* attributes are converted to alpha channel.
114  * So calculate depth from glformat, not from image depth.
115  *
116  * \verbatim image:GetOpenGLData() -> gldata: userdata, glformat: number [in Lua 5] \endverbatim
117  * \ingroup convert */
118 void* imImageGetOpenGLData(const(imImage)* image, int* glformat);
119 
120 /** Creates an image from an OpenGL data.
121  *
122  * \verbatim im.ImageCreateFromOpenGLData(width, height, glformat: number, gldata: userdata) -> image: imImage [in Lua 5] \endverbatim
123  * \ingroup convert */
124 imImage* imImageCreateFromOpenGLData(int width, int height, int glformat, const(void)* gldata);
125 
126 
127 /** \defgroup cnvutil Raw Data Conversion Utilities
128  * \par
129  * Utilities for raw data buffers.
130  * \par
131  * See \ref im_convert.h
132  * \ingroup imagerep */
133 
134 
135 /** Changes the packing of the data buffer. Both must have the same width, height and data_type. \n
136  * It can be used to copy data even if depth=1.
137  * \ingroup cnvutil */
138 void imConvertPacking(const(void)* src_data, void* dst_data, int width, int height, int src_depth, int dst_depth, int data_type, int src_is_packed);
139 
140 /** Changes in-place a MAP data into a RGB data. The data must have room for the RGB image. \n
141  * depth can be 3 or 4. count=width*height. \n
142  * \ingroup cnvutil */
143 void imConvertMapToRGB(ubyte* data, int count, int depth, int packed, c_long* palette, int palette_count);
144                        
145 
146 
147 /* Converts a RGB bitmap into a map bitmap using the median cut algorithm.
148  * Used only "im_convertcolor.cpp" implemented in "im_rgb2map.cpp". 
149  * Internal function kept here because of the compatibility module. 
150  * Will not be at the documentation. */
151 int imConvertRGB2Map(int width, int height, 
152               ubyte* red, ubyte* green, ubyte* blue, 
153               ubyte* map, c_long* palette, int* palette_count);