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_OUTPUT_FILE_H
38 #define INCLUDED_IMF_OUTPUT_FILE_H
40 //-----------------------------------------------------------------------------
44 //-----------------------------------------------------------------------------
46 #include <ImfHeader.h>
47 #include <ImfFrameBuffer.h>
48 #include <ImfThreading.h>
60 //-----------------------------------------------------------
61 // Constructor -- opens the file and writes the file header.
62 // The file header is also copied into the OutputFile object,
63 // and can later be accessed via the header() method.
64 // Destroying this OutputFile object automatically closes
67 // numThreads determines the number of threads that will be
68 // used to write the file (see ImfThreading.h).
69 //-----------------------------------------------------------
71 OutputFile (const char fileName[], const Header &header,
72 int numThreads = globalThreadCount());
75 //------------------------------------------------------------
76 // Constructor -- attaches the new OutputFile object to a file
77 // that has already been opened, and writes the file header.
78 // The file header is also copied into the OutputFile object,
79 // and can later be accessed via the header() method.
80 // Destroying this OutputFile object does not automatically
83 // numThreads determines the number of threads that will be
84 // used to write the file (see ImfThreading.h).
85 //------------------------------------------------------------
87 OutputFile (OStream &os, const Header &header,
88 int numThreads = globalThreadCount());
91 //-------------------------------------------------
94 // Destroying the OutputFile object before writing
95 // all scan lines within the data window results in
96 // an incomplete file.
97 //-------------------------------------------------
99 virtual ~OutputFile ();
102 //------------------------
103 // Access to the file name
104 //------------------------
106 const char * fileName () const;
109 //--------------------------
110 // Access to the file header
111 //--------------------------
113 const Header & header () const;
116 //-------------------------------------------------------
117 // Set the current frame buffer -- copies the FrameBuffer
118 // object into the OutputFile object.
120 // The current frame buffer is the source of the pixel
121 // data written to the file. The current frame buffer
122 // must be set at least once before writePixels() is
123 // called. The current frame buffer can be changed
124 // after each call to writePixels.
125 //-------------------------------------------------------
127 void setFrameBuffer (const FrameBuffer &frameBuffer);
130 //-----------------------------------
131 // Access to the current frame buffer
132 //-----------------------------------
134 const FrameBuffer & frameBuffer () const;
137 //-------------------------------------------------------------------
140 // writePixels(n) retrieves the next n scan lines worth of data from
141 // the current frame buffer, starting with the scan line indicated by
142 // currentScanLine(), and stores the data in the output file, and
143 // progressing in the direction indicated by header.lineOrder().
145 // To produce a complete and correct file, exactly m scan lines must
146 // be written, where m is equal to
147 // header().dataWindow().max.y - header().dataWindow().min.y + 1.
148 //-------------------------------------------------------------------
150 void writePixels (int numScanLines = 1);
153 //------------------------------------------------------------------
154 // Access to the current scan line:
156 // currentScanLine() returns the y coordinate of the first scan line
157 // that will be read from the current frame buffer during the next
158 // call to writePixels().
160 // If header.lineOrder() == INCREASING_Y:
162 // The current scan line before the first call to writePixels()
163 // is header().dataWindow().min.y. After writing each scan line,
164 // the current scan line is incremented by 1.
166 // If header.lineOrder() == DECREASING_Y:
168 // The current scan line before the first call to writePixels()
169 // is header().dataWindow().max.y. After writing each scan line,
170 // the current scan line is decremented by 1.
172 //------------------------------------------------------------------
174 int currentScanLine () const;
177 //--------------------------------------------------------------
178 // Shortcut to copy all pixels from an InputFile into this file,
179 // without uncompressing and then recompressing the pixel data.
180 // This file's header must be compatible with the InputFile's
181 // header: The two header's "dataWindow", "compression",
182 // "lineOrder" and "channels" attributes must be the same.
183 //--------------------------------------------------------------
185 void copyPixels (InputFile &in);
188 //--------------------------------------------------------------
189 // Updating the preview image:
191 // updatePreviewImage() supplies a new set of pixels for the
192 // preview image attribute in the file's header. If the header
193 // does not contain a preview image, updatePreviewImage() throws
196 // Note: updatePreviewImage() is necessary because images are
197 // often stored in a file incrementally, a few scan lines at a
198 // time, while the image is being generated. Since the preview
199 // image is an attribute in the file's header, it gets stored in
200 // the file as soon as the file is opened, but we may not know
201 // what the preview image should look like until we have written
202 // the last scan line of the main image.
204 //--------------------------------------------------------------
206 void updatePreviewImage (const PreviewRgba newPixels[]);
209 //---------------------------------------------------------
210 // Break a scan line -- for testing and debugging only:
212 // breakScanLine(y,p,n,c) introduces an error into the
213 // output file by writing n copies of character c, starting
214 // p bytes from the beginning of the pixel data block that
215 // contains scan line y.
217 // Warning: Calling this function usually results in a
218 // broken image file. The file or parts of it may not
219 // be readable, or the file may contain bad data.
221 //---------------------------------------------------------
223 void breakScanLine (int y, int offset, int length, char c);
230 OutputFile (const OutputFile &); // not implemented
231 OutputFile & operator = (const OutputFile &); // not implemented
233 void initialize (const Header &header);