/src/FreeImage/Source/OpenEXR/IlmImf/ImfAcesFile.h

  1///////////////////////////////////////////////////////////////////////////
  2//
  3// Copyright (c) 2007, Industrial Light & Magic, a division of Lucas
  4// Digital Ltd. LLC
  5// 
  6// All rights reserved.
  7// 
  8// Redistribution and use in source and binary forms, with or without
  9// modification, are permitted provided that the following conditions are
 10// met:
 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
 16// distribution.
 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. 
 20// 
 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.
 32//
 33///////////////////////////////////////////////////////////////////////////
 34
 35
 36
 37#ifndef INCLUDED_IMF_ACES_FILE_H
 38#define INCLUDED_IMF_ACES_FILE_H
 39
 40
 41//-----------------------------------------------------------------------------
 42//
 43//	ACES image file I/O.
 44//	
 45//	This header file declares two classes that directly support
 46//	image file input and output according to the Academy Image
 47//	Interchange Framework.
 48//	
 49//	The Academy Image Interchange file format is a subset of OpenEXR:
 50//	
 51//	    - Images are stored as scanlines.  Tiles are not allowed.
 52//	
 53//	    - Images contain three color channels, either
 54//		    R, G, B (red, green, blue) or
 55//		    Y, RY, BY (luminance, sub-sampled chroma)
 56//	
 57//	    - Images may optionally contain an alpha channel.
 58//	
 59//	    - Only three compression types are allowed:
 60//		    - NO_COMPRESSION (file is not compressed)
 61//		    - PIZ_COMPRESSION (lossless)
 62//		    - B44A_COMPRESSION (lossy)
 63//	
 64//	    - The "chromaticities" header attribute must specify
 65//	      the ACES RGB primaries and white point.
 66//	
 67//	class AcesOutputFile writes an OpenEXR file, enforcing the
 68//	restrictions listed above.  Pixel data supplied by application
 69//	software must already be in the ACES RGB space.
 70//	
 71//	class AcesInputFile reads an OpenEXR file.  Pixel data delivered
 72//	to application software is guaranteed to be in the ACES RGB space.
 73//	If the RGB space of the file is not the same as the ACES space,
 74//	then the pixels are automatically converted: the pixels are
 75//	converted to CIE XYZ, a color adaptation transform shifts the
 76//	white point, and the result is converted to ACES RGB.
 77//
 78//-----------------------------------------------------------------------------
 79
 80#include <ImfHeader.h>
 81#include <ImfRgba.h>
 82#include "ImathVec.h"
 83#include "ImathBox.h"
 84#include <ImfThreading.h>
 85#include <string>
 86
 87namespace Imf {
 88
 89
 90class RgbaOutputFile;
 91class RgbaInputFile;
 92struct PreviewRgba;
 93class Chromaticities;
 94
 95//
 96// ACES red, green, blue and white-point chromaticities.
 97//
 98
 99const Chromaticities &	acesChromaticities ();
100
101
102//
103// ACES output file.
104//
105
106class AcesOutputFile
107{
108  public:
109
110    //---------------------------------------------------
111    // Constructor -- header is constructed by the caller
112    //---------------------------------------------------
113
114    AcesOutputFile (const std::string &name,
115		    const Header &header,
116		    RgbaChannels rgbaChannels = WRITE_RGBA,
117                    int numThreads = globalThreadCount());
118
119
120    //----------------------------------------------------
121    // Constructor -- header is constructed by the caller,
122    // file is opened by the caller, destructor will not
123    // automatically close the file.
124    //----------------------------------------------------
125
126    AcesOutputFile (OStream &os,
127		    const Header &header,
128		    RgbaChannels rgbaChannels = WRITE_RGBA,
129                    int numThreads = globalThreadCount());
130
131
132    //----------------------------------------------------------------
133    // Constructor -- header data are explicitly specified as function
134    // call arguments (empty dataWindow means "same as displayWindow")
135    //----------------------------------------------------------------
136
137    AcesOutputFile (const std::string &name,
138		    const Imath::Box2i &displayWindow,
139		    const Imath::Box2i &dataWindow = Imath::Box2i(),
140		    RgbaChannels rgbaChannels = WRITE_RGBA,
141		    float pixelAspectRatio = 1,
142		    const Imath::V2f screenWindowCenter = Imath::V2f (0, 0),
143		    float screenWindowWidth = 1,
144		    LineOrder lineOrder = INCREASING_Y,
145		    Compression compression = PIZ_COMPRESSION,
146                    int numThreads = globalThreadCount());
147
148
149    //-----------------------------------------------
150    // Constructor -- like the previous one, but both
151    // the display window and the data window are
152    // Box2i (V2i (0, 0), V2i (width - 1, height -1))
153    //-----------------------------------------------
154
155    AcesOutputFile (const std::string &name,
156		    int width,
157		    int height,
158		    RgbaChannels rgbaChannels = WRITE_RGBA,
159		    float pixelAspectRatio = 1,
160		    const Imath::V2f screenWindowCenter = Imath::V2f (0, 0),
161		    float screenWindowWidth = 1,
162		    LineOrder lineOrder = INCREASING_Y,
163		    Compression compression = PIZ_COMPRESSION,
164                    int numThreads = globalThreadCount());
165
166
167    //-----------
168    // Destructor
169    //-----------
170
171    virtual ~AcesOutputFile ();
172
173
174    //------------------------------------------------
175    // Define a frame buffer as the pixel data source:
176    // Pixel (x, y) is at address
177    //
178    //  base + x * xStride + y * yStride
179    //
180    //------------------------------------------------
181
182    void			setFrameBuffer (const Rgba *base,
183						size_t xStride,
184						size_t yStride);
185
186
187    //-------------------------------------------------
188    // Write pixel data (see class Imf::OutputFile)
189    // The pixels are assumed to contain ACES RGB data.
190    //-------------------------------------------------
191
192    void			writePixels (int numScanLines = 1);
193    int				currentScanLine () const;
194
195
196    //--------------------------
197    // Access to the file header
198    //--------------------------
199
200    const Header &		header () const;
201    const Imath::Box2i &	displayWindow () const;
202    const Imath::Box2i &	dataWindow () const;
203    float			pixelAspectRatio () const;
204    const Imath::V2f		screenWindowCenter () const;
205    float			screenWindowWidth () const;
206    LineOrder			lineOrder () const;
207    Compression			compression () const;
208    RgbaChannels		channels () const;
209
210
211    // --------------------------------------------------------------------
212    // Update the preview image (see Imf::OutputFile::updatePreviewImage())
213    // --------------------------------------------------------------------
214
215    void			updatePreviewImage (const PreviewRgba[]);
216
217
218  private:
219
220    AcesOutputFile (const AcesOutputFile &);		  // not implemented
221    AcesOutputFile & operator = (const AcesOutputFile &); // not implemented
222
223    class Data;
224
225    Data *			_data;
226};
227
228
229//
230// ACES input file
231//
232
233class AcesInputFile
234{
235  public:
236
237    //-------------------------------------------------------
238    // Constructor -- opens the file with the specified name,
239    // destructor will automatically close the file.
240    //-------------------------------------------------------
241
242    AcesInputFile (const std::string &name,
243		   int numThreads = globalThreadCount());
244
245
246    //-----------------------------------------------------------
247    // Constructor -- attaches the new AcesInputFile object to a
248    // file that has already been opened by the caller.
249    // Destroying the AcesInputFile object will not automatically
250    // close the file.
251    //-----------------------------------------------------------
252
253    AcesInputFile (IStream &is,
254		   int numThreads = globalThreadCount());
255
256
257    //-----------
258    // Destructor
259    //-----------
260
261    virtual ~AcesInputFile ();
262
263
264    //-----------------------------------------------------
265    // Define a frame buffer as the pixel data destination:
266    // Pixel (x, y) is at address
267    //
268    //  base + x * xStride + y * yStride
269    //
270    //-----------------------------------------------------
271
272    void			setFrameBuffer (Rgba *base,
273						size_t xStride,
274						size_t yStride);
275
276
277    //--------------------------------------------
278    // Read pixel data (see class Imf::InputFile)
279    // Pixels returned will contain ACES RGB data.
280    //--------------------------------------------
281
282    void			readPixels (int scanLine1, int scanLine2);
283    void			readPixels (int scanLine);
284
285
286    //--------------------------
287    // Access to the file header
288    //--------------------------
289
290    const Header &		header () const;
291    const Imath::Box2i &	displayWindow () const;
292    const Imath::Box2i &	dataWindow () const;
293    float			pixelAspectRatio () const;
294    const Imath::V2f		screenWindowCenter () const;
295    float			screenWindowWidth () const;
296    LineOrder			lineOrder () const;
297    Compression			compression () const;
298    RgbaChannels		channels () const;
299    const char *                fileName () const;
300    bool			isComplete () const;
301
302
303    //----------------------------------
304    // Access to the file format version
305    //----------------------------------
306
307    int				version () const;
308
309  private:
310
311    AcesInputFile (const AcesInputFile &);		  // not implemented
312    AcesInputFile & operator = (const AcesInputFile &);   // not implemented
313
314    class Data;
315
316    Data *			_data;
317};
318
319
320} // namespace Imf
321
322#endif