1 ///////////////////////////////////////////////////////////////////////////
3 // Copyright (c) 2004, Industrial Light & Magic, a division of Lucas
6 // All rights reserved.
8 // Redistribution and use in source and binary forms, with or without
9 // modification, are permitted provided that the following conditions are
11 // * Redistributions of source code must retain the above copyright
12 // notice, this list of conditions and the following disclaimer.
13 // * Redistributions in binary form must reproduce the above
14 // copyright notice, this list of conditions and the following disclaimer
15 // in the documentation and/or other materials provided with the
17 // * Neither the name of Industrial Light & Magic nor the names of
18 // its contributors may be used to endorse or promote products derived
19 // from this software without specific prior written permission.
21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 ///////////////////////////////////////////////////////////////////////////
37 #ifndef INCLUDED_IMF_RGBA_FILE_H
38 #define INCLUDED_IMF_RGBA_FILE_H
41 //-----------------------------------------------------------------------------
43 // Simplified RGBA image I/O
45 // class RgbaOutputFile
46 // class RgbaInputFile
48 //-----------------------------------------------------------------------------
50 #include <ImfHeader.h>
51 #include <ImfFrameBuffer.h>
56 #include <ImfThreading.h>
73 //---------------------------------------------------
74 // Constructor -- header is constructed by the caller
75 //---------------------------------------------------
77 RgbaOutputFile (const char name[],
79 RgbaChannels rgbaChannels = WRITE_RGBA,
80 int numThreads = globalThreadCount());
83 //----------------------------------------------------
84 // Constructor -- header is constructed by the caller,
85 // file is opened by the caller, destructor will not
86 // automatically close the file.
87 //----------------------------------------------------
89 RgbaOutputFile (OStream &os,
91 RgbaChannels rgbaChannels = WRITE_RGBA,
92 int numThreads = globalThreadCount());
95 //----------------------------------------------------------------
96 // Constructor -- header data are explicitly specified as function
97 // call arguments (empty dataWindow means "same as displayWindow")
98 //----------------------------------------------------------------
100 RgbaOutputFile (const char name[],
101 const Imath::Box2i &displayWindow,
102 const Imath::Box2i &dataWindow = Imath::Box2i(),
103 RgbaChannels rgbaChannels = WRITE_RGBA,
104 float pixelAspectRatio = 1,
105 const Imath::V2f screenWindowCenter = Imath::V2f (0, 0),
106 float screenWindowWidth = 1,
107 LineOrder lineOrder = INCREASING_Y,
108 Compression compression = PIZ_COMPRESSION,
109 int numThreads = globalThreadCount());
112 //-----------------------------------------------
113 // Constructor -- like the previous one, but both
114 // the display window and the data window are
115 // Box2i (V2i (0, 0), V2i (width - 1, height -1))
116 //-----------------------------------------------
118 RgbaOutputFile (const char name[],
121 RgbaChannels rgbaChannels = WRITE_RGBA,
122 float pixelAspectRatio = 1,
123 const Imath::V2f screenWindowCenter = Imath::V2f (0, 0),
124 float screenWindowWidth = 1,
125 LineOrder lineOrder = INCREASING_Y,
126 Compression compression = PIZ_COMPRESSION,
127 int numThreads = globalThreadCount());
134 virtual ~RgbaOutputFile ();
137 //------------------------------------------------
138 // Define a frame buffer as the pixel data source:
139 // Pixel (x, y) is at address
141 // base + x * xStride + y * yStride
143 //------------------------------------------------
145 void setFrameBuffer (const Rgba *base,
150 //---------------------------------------------
151 // Write pixel data (see class Imf::OutputFile)
152 //---------------------------------------------
154 void writePixels (int numScanLines = 1);
155 int currentScanLine () const;
158 //--------------------------
159 // Access to the file header
160 //--------------------------
162 const Header & header () const;
163 const FrameBuffer & frameBuffer () const;
164 const Imath::Box2i & displayWindow () const;
165 const Imath::Box2i & dataWindow () const;
166 float pixelAspectRatio () const;
167 const Imath::V2f screenWindowCenter () const;
168 float screenWindowWidth () const;
169 LineOrder lineOrder () const;
170 Compression compression () const;
171 RgbaChannels channels () const;
174 // --------------------------------------------------------------------
175 // Update the preview image (see Imf::OutputFile::updatePreviewImage())
176 // --------------------------------------------------------------------
178 void updatePreviewImage (const PreviewRgba[]);
181 //-----------------------------------------------------------------------
182 // Rounding control for luminance/chroma images:
184 // If the output file contains luminance and chroma channels (WRITE_YC
185 // or WRITE_YCA), then the the significands of the luminance and
186 // chroma values are rounded to roundY and roundC bits respectively (see
187 // function half::round()). Rounding improves compression with minimal
188 // image degradation, usually much less than the degradation caused by
189 // chroma subsampling. By default, roundY is 7, and roundC is 5.
191 // If the output file contains RGB channels or a luminance channel,
192 // without chroma, then no rounding is performed.
193 //-----------------------------------------------------------------------
195 void setYCRounding (unsigned int roundY,
196 unsigned int roundC);
199 //----------------------------------------------------
200 // Break a scan line -- for testing and debugging only
201 // (see Imf::OutputFile::updatePreviewImage()
203 // Warning: Calling this function usually results in a
204 // broken image file. The file or parts of it may not
205 // be readable, or the file may contain bad data.
207 //----------------------------------------------------
209 void breakScanLine (int y,
215 RgbaOutputFile (const RgbaOutputFile &); // not implemented
216 RgbaOutputFile & operator = (const RgbaOutputFile &); // not implemented
220 OutputFile * _outputFile;
233 //-------------------------------------------------------
234 // Constructor -- opens the file with the specified name,
235 // destructor will automatically close the file.
236 //-------------------------------------------------------
238 RgbaInputFile (const char name[], int numThreads = globalThreadCount());
241 //-----------------------------------------------------------
242 // Constructor -- attaches the new RgbaInputFile object to a
243 // file that has already been opened by the caller.
244 // Destroying the RgbaInputFile object will not automatically
246 //-----------------------------------------------------------
248 RgbaInputFile (IStream &is, int numThreads = globalThreadCount());
255 virtual ~RgbaInputFile ();
257 //-----------------------------------------------------
258 // Define a frame buffer as the pixel data destination:
259 // Pixel (x, y) is at address
261 // base + x * xStride + y * yStride
263 //-----------------------------------------------------
265 void setFrameBuffer (Rgba *base,
270 //-------------------------------------------
271 // Read pixel data (see class Imf::InputFile)
272 //-------------------------------------------
274 void readPixels (int scanLine1, int scanLine2);
275 void readPixels (int scanLine);
278 //--------------------------
279 // Access to the file header
280 //--------------------------
282 const Header & header () const;
283 const FrameBuffer & frameBuffer () const;
284 const Imath::Box2i & displayWindow () const;
285 const Imath::Box2i & dataWindow () const;
286 float pixelAspectRatio () const;
287 const Imath::V2f screenWindowCenter () const;
288 float screenWindowWidth () const;
289 LineOrder lineOrder () const;
290 Compression compression () const;
291 RgbaChannels channels () const;
292 const char * fileName () const;
293 bool isComplete () const;
295 //----------------------------------
296 // Access to the file format version
297 //----------------------------------
299 int version () const;
303 RgbaInputFile (const RgbaInputFile &); // not implemented
304 RgbaInputFile & operator = (const RgbaInputFile &); // not implemented
308 InputFile * _inputFile;