HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups 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 = "*", bool ocio = false);
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  /// Specifies the destination colorspace when reading, and the source
162  /// colorspace when writing (ie, the colorspace the raster is in, not the
163  /// file contents). Default colorspace is the scene linear role.
164  /// Only active if an OCIO LUT is used.
165  void setOCIOColorspace(const char *ocio_colorspace);
166 
167  /// One or more looks (color transforms) that are applied to the image
168  /// after reading or before writing, in order of specification (whitespace
169  /// separated list).
170  void setOCIOLooks(const char *looks);
171 
172  // INFORMATION ----------------------------------------------------------
173 
174  /// @brief Returns information about the image's alpha channel
175  /// Checks to see if the alpha plane is constant 1, cutout 0/1,
176  /// constant valued, varying, out-of-range (>1 or <0) or absent. Load only.
177  void detectAlphaDetails();
178 
179  // FORMAT SPECIFIC OPTIONS ----------------------------------------------
180 
181  /// set an input/output tag option for the format.
182  void setOption(const char *option, const char *value);
183 
184  /// options are a list of argument pairs, such as "artist", "Tom Smith".
185  /// The options list is terminated by a NULL.
186  void setOptions(const char **options);
187 
188  /// options are in a whitespace separated string "Artist 'Tom Jones'"
189  void setOptionsString(const char *option_pair_string);
190 
191  /// options are specified in the IMG_TileOptions structure
192  void setOptions(const IMG_TileOptions &info_with_options);
193 
194  /// set options based on a UT_Options (this is similar to using
195  /// IMG_TileOptions)
196  void setOptions(const UT_Options &options);
197 
198  /// @brief Enable the tile inteface for reading or writing
199  /// If called, we're reading or writing tiles using IMG_File::readTile
200  /// and IMG_File::writeTile. The scanline versions will not work.
201  void useTileInterface();
202 
203  /// If set, files will not report errors and subsequent scanlines
204  /// will be returned as black.
205  void continueOnError();
206 
207 private:
208  IMG_ImageType myImageType;
209  IMG_DataType myDataType;
210  IMG_ColorModel myColorModel;
211  IMG_ComponentOrder myComponentOrder;
212  IMG_XOrientation myOrientX;
213  IMG_YOrientation myOrientY;
214  int myMaxX, myMaxY;
215  int myResX, myResY;
216  fpreal myScaleX, myScaleY;
217  UT_FilterType myFilterType;
218  fpreal myGamma;
219  IMG_Interleave myInterleaved;
220  PXL_LumFunction myLumFunc;
221  fpreal myGain;
222  fpreal myOffset;
223 
224  bool myFlipHorizontal : 1,
225  myFlipVertical : 1,
226  myFlopImage : 1,
227  myReadDataWindowOnly :1,
228  myReadAreaFlag :1,
229  myReadUVAreaFlag : 1,
230  myUseTiles :1,
231  myUseLUT : 1,
232  myPowerTwoRes :1,
233  myResLimit:1,
234  myPreserveAspect : 1,
235  myAlphaSplit : 1,
236  myContinueOnError : 1,
237  myAlphaDetect: 1,
238  myIsNormal: 1,
239  myLutIsOCIO : 1;
240 
241  UT_DimRect myReadArea;
242  fpreal myReadUVArea[4];
243  UT_String myLUTFilename;
244  UT_String myLUTScope;
245  UT_String myGammaScope;
246  UT_String mySelectPlaneName;
247  UT_IntArray mySelectPlaneIndex;
248  UT_StringHolder myOCIOColorspace;
249  UT_StringHolder myOCIOLooks;
250 
251  UT_StringArray myOptions;
252  UT_StringArray myOptionValues;
253 
254  friend class IMG_File;
255 };
256 
257 
258 
259 #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:270
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