HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
IMG_FileParms.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: IMG_FileParm.h ( IMG Library, C++)
7  *
8  * COMMENTS:
9  * Parameter class for options to IMG_File::open() and IMG_File::create()
10  */
11 #ifndef __IMG_FILE_PARMS_H__
12 #define __IMG_FILE_PARMS_H__
13 
14 #include "IMG_API.h"
15 
16 #include <SYS/SYS_Types.h>
17 #include <UT/UT_FilterType.h>
18 #include <UT/UT_StringArray.h>
19 #include <UT/UT_IntArray.h>
20 #include <UT/UT_Rect.h>
21 #include <PXL/PXL_LumFuncs.h>
22 
23 #include "IMG_FileTypes.h"
24 
25 class UT_Options;
26 class IMG_TileOptions;
27 class IMG_Stat;
28 class IMG_Format;
29 
30 /// @brief File options for manipulating image data on load or save.
31 /// This class allows you to modify the incoming or outgoing image data by
32 /// scaling, flipping, converting or cropping the data. It can be optionally
33 /// passed to IMG_File::open() or IMG_File::create()
35 {
36 public:
37  IMG_FileParms();
38 
39  /// This method turns off any option that would result in image
40  /// translation.
41  void readAsIs();
42 
43  // DATA ORGANIZATION ----------------------------------------------------
44 
45  /// @brief Convert to a different data type
46  /// convert the image to this data type, if needed (default = use native)
47  void setDataType(IMG_DataType dt);
48 
49  /// @brief Convert to a different number of pixel components
50  /// convert to a standard color model, if needed (RGB, RGBA, single).
51  /// When moving from fewer components to more components, the
52  /// data is either duplicated (1chan->RGB) or generated (RGB-RGBA, A=1).
53  void setColorModel(IMG_ColorModel cm);
54 
55  /// @brief Convert to either an RGBA or ABGR ordering
56  /// converts the component ordering to RGBA or ABGR (or RGB/BGR, RG/GR)
57  /// without forcing the color model to a specific number of components.
58  void setComponentOrder(IMG_ComponentOrder order);
59 
60  /// @brief Interleaves or deinterleaves pixel data
61  /// Determines how to format the data.
62  /// - IMG_INTERLEAVE_AS_IS - leave it interleaved or non, as in the file.
63  /// - IMG_INTERLEAVED - always interleave (rgbrgbrgb). Default.
64  /// - IMG_NON_INTERLEAVED - always non-interleaved (rrrgggbbb)
65  void setInterleaved(IMG_Interleave i);
66 
67  /// If the color model is set to IMG_1CHAN, and the actual color model
68  /// is RGB or higher, this method determines how to convert the vector
69  /// into a scalar. By default, the luminance is taken.
70  void setLuminanceFunc(PXL_LumFunction f);
71 
72  /// If true, alpha will be read into its own plane, instead of an RGBA
73  /// color plane. Color will be read as its own plane as well, RGB.
74  void readAlphaAsPlane();
75 
76  /// If demoting from a deep raster to an RGB(A) image, these methods
77  /// allow you to specify the plane(s) to copy to RGB(A), by name or index.
78  /// Selects a plane by index. Indices are specified from 1 to # planes.
79  void selectPlanes(const UT_IntArray &planeindices);
80 
81  /// If demoting from a deep raster to an RGB(A) image, these methods
82  /// allow you to specify the plane(s) to copy to RGB(A), by name or index.
83  /// Selects several planes by numeric pattern, ie. "1", "1 3 4", "[1-3] 5"
84  void selectPlanes(const char *pattern);
85 
86  /// If demoting from a deep raster to an RGB(A) image, these methods
87  /// allow you to specify the plane(s) to copy to RGB(A), by name or index.
88  /// Selects serveral planes by name pattern, such as "C", "C A Pz" "P? C*"
89  void selectPlaneNames(const char *name);
90 
91 
92  /// RESOLUTION -----------------------------------------------------------
93  /// using these methods always scales. To crop, use the data window methods
94  /// Note that the filter is shared, so if more than one of these is called,
95  /// the last filter setting is used.
96 
97  /// Scale the image to resolution (x,y). (0 = use original dimension)
98  void scaleImageTo(int x, int y, UT_FilterType ft=UT_FILTER_BOX);
99 
100  /// scale the image by scaling factors (x,y).
101  void scaleImageBy(fpreal x, fpreal y, UT_FilterType ft=UT_FILTER_BOX);
102 
103  /// limit the image to a maximum resolution. Scale to this res, preserving
104  /// the aspect ratio if requested.
105  void limitImageRes(int x, int y, UT_FilterType ft=UT_FILTER_BOX,
106  bool preserve_aspect = true);
107 
108  /// images must be read as powers of two. Does not preserve aspect ratio.
109  void powerTwoOnly();
110 
111  // DATA WINDOW ---------------------------------------------------------
112 
113  /// Normally, a data window is expanded or cropped to the image resolution.
114  /// calling this will always read only the data window.
115  /// Used only for reading.
116  void setDataWindowOnly();
117 
118  /// read the image region in 'area' only (even if we need to crop or expand
119  /// the image to fill it). Used only for reading.
120  void setWindow(const UT_DimRect &area);
121 
122  /// read the image region in 'area' in UV coords. Used only for reading.
123  void setWindow(float u1, float v1, float u2, float v2);
124 
125  // ORIENTATION ----------------------------------------------------------
126 
127  /// options for orienting and flipping the image. Default orientation is
128  /// LEFT_FIRST, BOTTOM_FIRST. You can set each to 'none' if you don't care.
129  void orientImage(IMG_XOrientation x, IMG_YOrientation y);
130 
131  /// @brief Flip the image in either direction.
132  /// flip the images in either direction. May cancel out any orientation
133  /// flipping.
134  /// @{
135  void flipImageVertical();
136  void flipImageHorizontal();
137  /// @}
138 
139  /// rotate the image 90', flopping it on its side.
140  void flopImage();
141 
142 
143  // COLOR CORRECTION -----------------------------------------------------
144 
145  /// @brief Color correct an image using a LUT
146  /// apply a lookup table to the data, but only those planes that match the
147  /// scope (ie, "C spec diff", "C*", "*beauty*")
148  void applyLUT(const char *lut, const char *plane_scope = "*");
149 
150  /// @brief Color correct an image using a gamma setting
151  /// Apply gamma to the planes matching the scope (ie, "C spec diff", "C*",
152  /// "*beauty*")
153  void applyGamma(fpreal gamma, const char *gamma_scope = "*");
154 
155  /// Set the gamma and scope to apply any needed gamma correction to planes
156  /// being written. This overwrites any applyGamma() changes.
157  void adjustGammaForFormat(const IMG_Stat &stat,
158  const IMG_Format *format,
159  IMG_DataType override_type = IMG_DT_ANY);
160 
161  // INFORMATION ----------------------------------------------------------
162 
163  /// @brief Returns information about the image's alpha channel
164  /// Checks to see if the alpha plane is constant 1, cutout 0/1,
165  /// constant valued, varying, out-of-range (>1 or <0) or absent. Load only.
166  void detectAlphaDetails();
167 
168  // FORMAT SPECIFIC OPTIONS ----------------------------------------------
169 
170  /// set an input/output tag option for the format.
171  void setOption(const char *option, const char *value);
172 
173  /// options are a list of argument pairs, such as "artist", "Tom Smith".
174  /// The options list is terminated by a NULL.
175  void setOptions(const char **options);
176 
177  /// options are in a whitespace separated string "Artist 'Tom Jones'"
178  void setOptionsString(const char *option_pair_string);
179 
180  /// options are specified in the IMG_TileOptions structure
181  void setOptions(const IMG_TileOptions &info_with_options);
182 
183  /// set options based on a UT_Options (this is similar to using
184  /// IMG_TileOptions)
185  void setOptions(const UT_Options &options);
186 
187  /// @brief Enable the tile inteface for reading or writing
188  /// If called, we're reading or writing tiles using IMG_File::readTile
189  /// and IMG_File::writeTile. The scanline versions will not work.
190  void useTileInterface();
191 
192  /// If set, files will not report errors and subsequent scanlines
193  /// will be returned as black.
194  void continueOnError();
195 
196 private:
197  IMG_ImageType myImageType;
198  IMG_DataType myDataType;
199  IMG_ColorModel myColorModel;
200  IMG_ComponentOrder myComponentOrder;
201  IMG_XOrientation myOrientX;
202  IMG_YOrientation myOrientY;
203  int myMaxX, myMaxY;
204  int myResX, myResY;
205  fpreal myScaleX, myScaleY;
206  UT_FilterType myFilterType;
207  fpreal myGamma;
208  IMG_Interleave myInterleaved;
209  PXL_LumFunction myLumFunc;
210  fpreal myGain;
211  fpreal myOffset;
212 
213  bool myFlipHorizontal : 1,
214  myFlipVertical : 1,
215  myFlopImage : 1,
216  myReadDataWindowOnly :1,
217  myReadAreaFlag :1,
218  myReadUVAreaFlag : 1,
219  myUseTiles :1,
220  myUseLUT : 1,
221  myPowerTwoRes :1,
222  myResLimit:1,
223  myPreserveAspect : 1,
224  myAlphaSplit : 1,
225  myContinueOnError : 1,
226  myAlphaDetect: 1,
227  myIsNormal: 1;
228 
229  UT_DimRect myReadArea;
230  fpreal myReadUVArea[4];
231  UT_String myLUTFilename;
232  UT_String myLUTScope;
233  UT_String myGammaScope;
234  UT_String mySelectPlaneName;
235  UT_IntArray mySelectPlaneIndex;
236 
237  UT_StringArray myOptions;
238  UT_StringArray myOptionValues;
239 
240  friend class IMG_File;
241 };
242 
243 
244 
245 #endif
IMG_ImageType
Type of image we want to create or have opened.
IMG_XOrientation
GLint y
Definition: glcorearb.h:102
GLfloat GLfloat GLfloat v2
Definition: glcorearb.h:817
UT_FilterType
Definition: UT_FilterType.h:16
png_uint_32 i
Definition: png.h:2877
PXL_LumFunction
Definition: PXL_LumFuncs.h:18
#define IMG_API
Definition: IMG_API.h:10
GLfloat f
Definition: glcorearb.h:1925
IMG_DataType
Definition: IMG_FileTypes.h:17
Generic interface for reading and writing image files. This class handles the reading and writing of ...
Definition: IMG_File.h:54
GLuint const GLchar * name
Definition: glcorearb.h:785
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:107
IMG_YOrientation
GLsizei const GLfloat * value
Definition: glcorearb.h:823
double fpreal
Definition: SYS_Types.h:269
A map of string to various well defined value types.
Definition: UT_Options.h:42
IMG_Interleave
Definition: IMG_FileTypes.h:77
File options for manipulating image data on load or save. This class allows you to modify the incomin...
Definition: IMG_FileParms.h:34
IMG_ColorModel
Definition: IMG_FileTypes.h:53
GLint GLenum GLint x
Definition: glcorearb.h:408
GLfloat GLfloat v1
Definition: glcorearb.h:816
IMG_ComponentOrder
Definition: IMG_FileTypes.h:84
Contains the details of a specific image file, used by IMG_File. This class contains all the high-lev...
Definition: IMG_Stat.h:40
GA_API const UT_StringHolder area