HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ImfOutputFile.h
Go to the documentation of this file.
1 //
2 // SPDX-License-Identifier: BSD-3-Clause
3 // Copyright (c) Contributors to the OpenEXR Project.
4 //
5 
6 #ifndef INCLUDED_IMF_OUTPUT_FILE_H
7 #define INCLUDED_IMF_OUTPUT_FILE_H
8 
9 //-----------------------------------------------------------------------------
10 //
11 // class OutputFile
12 //
13 //-----------------------------------------------------------------------------
14 
15 #include "ImfForward.h"
16 
17 #include "ImfGenericOutputFile.h"
18 #include "ImfThreading.h"
19 
21 
23 {
24 public:
25  //-----------------------------------------------------------
26  // Constructor -- opens the file and writes the file header.
27  // The file header is also copied into the OutputFile object,
28  // and can later be accessed via the header() method.
29  // Destroying this OutputFile object automatically closes
30  // the file.
31  //
32  // numThreads determines the number of threads that will be
33  // used to write the file (see ImfThreading.h).
34  //-----------------------------------------------------------
35 
37  OutputFile (
38  const char fileName[],
39  const Header& header,
40  int numThreads = globalThreadCount ());
41 
42  //------------------------------------------------------------
43  // Constructor -- attaches the new OutputFile object to a file
44  // that has already been opened, and writes the file header.
45  // The file header is also copied into the OutputFile object,
46  // and can later be accessed via the header() method.
47  // Destroying this OutputFile object does not automatically
48  // close the file.
49  //
50  // numThreads determines the number of threads that will be
51  // used to write the file (see ImfThreading.h).
52  //------------------------------------------------------------
53 
55  OutputFile (
57  const Header& header,
58  int numThreads = globalThreadCount ());
59 
60  //-------------------------------------------------
61  // Destructor
62  //
63  // Destroying the OutputFile object before writing
64  // all scan lines within the data window results in
65  // an incomplete file.
66  //-------------------------------------------------
67 
69  virtual ~OutputFile ();
70 
71  //------------------------
72  // Access to the file name
73  //------------------------
74 
76  const char* fileName () const;
77 
78  //--------------------------
79  // Access to the file header
80  //--------------------------
81 
83  const Header& header () const;
84 
85  //-------------------------------------------------------
86  // Set the current frame buffer -- copies the FrameBuffer
87  // object into the OutputFile object.
88  //
89  // The current frame buffer is the source of the pixel
90  // data written to the file. The current frame buffer
91  // must be set at least once before writePixels() is
92  // called. The current frame buffer can be changed
93  // after each call to writePixels.
94  //-------------------------------------------------------
95 
97  void setFrameBuffer (const FrameBuffer& frameBuffer);
98 
99  //-----------------------------------
100  // Access to the current frame buffer
101  //-----------------------------------
102 
103  IMF_EXPORT
104  const FrameBuffer& frameBuffer () const;
105 
106  //-------------------------------------------------------------------
107  // Write pixel data:
108  //
109  // writePixels(n) retrieves the next n scan lines worth of data from
110  // the current frame buffer, starting with the scan line indicated by
111  // currentScanLine(), and stores the data in the output file, and
112  // progressing in the direction indicated by header.lineOrder().
113  //
114  // To produce a complete and correct file, exactly m scan lines must
115  // be written, where m is equal to
116  // header().dataWindow().max.y - header().dataWindow().min.y + 1.
117  //-------------------------------------------------------------------
118 
119  IMF_EXPORT
120  void writePixels (int numScanLines = 1);
121 
122  //------------------------------------------------------------------
123  // Access to the current scan line:
124  //
125  // currentScanLine() returns the y coordinate of the first scan line
126  // that will be read from the current frame buffer during the next
127  // call to writePixels().
128  //
129  // If header.lineOrder() == INCREASING_Y:
130  //
131  // The current scan line before the first call to writePixels()
132  // is header().dataWindow().min.y. After writing each scan line,
133  // the current scan line is incremented by 1.
134  //
135  // If header.lineOrder() == DECREASING_Y:
136  //
137  // The current scan line before the first call to writePixels()
138  // is header().dataWindow().max.y. After writing each scan line,
139  // the current scan line is decremented by 1.
140  //
141  //------------------------------------------------------------------
142 
143  IMF_EXPORT
144  int currentScanLine () const;
145 
146  //--------------------------------------------------------------
147  // Shortcut to copy all pixels from an InputFile into this file,
148  // without uncompressing and then recompressing the pixel data.
149  // This file's header must be compatible with the InputFile's
150  // header: The two header's "dataWindow", "compression",
151  // "lineOrder" and "channels" attributes must be the same.
152  //--------------------------------------------------------------
153 
154  IMF_EXPORT
155  void copyPixels (InputFile& in);
156 
157  //-------------------------------------------------------------
158  // Shortcut to copy all pixels from an InputPart into this file
159  // - equivalent to copyPixel(InputFile &in) but for multipart files
160  //---------------------------------------------------------------
161 
162  IMF_EXPORT
163  void copyPixels (InputPart& in);
164 
165  //--------------------------------------------------------------
166  // Updating the preview image:
167  //
168  // updatePreviewImage() supplies a new set of pixels for the
169  // preview image attribute in the file's header. If the header
170  // does not contain a preview image, updatePreviewImage() throws
171  // an IEX_NAMESPACE::LogicExc.
172  //
173  // Note: updatePreviewImage() is necessary because images are
174  // often stored in a file incrementally, a few scan lines at a
175  // time, while the image is being generated. Since the preview
176  // image is an attribute in the file's header, it gets stored in
177  // the file as soon as the file is opened, but we may not know
178  // what the preview image should look like until we have written
179  // the last scan line of the main image.
180  //
181  //--------------------------------------------------------------
182 
183  IMF_EXPORT
184  void updatePreviewImage (const PreviewRgba newPixels[]);
185 
186  //---------------------------------------------------------
187  // Break a scan line -- for testing and debugging only:
188  //
189  // breakScanLine(y,p,n,c) introduces an error into the
190  // output file by writing n copies of character c, starting
191  // p bytes from the beginning of the pixel data block that
192  // contains scan line y.
193  //
194  // Warning: Calling this function usually results in a
195  // broken image file. The file or parts of it may not
196  // be readable, or the file may contain bad data.
197  //
198  //---------------------------------------------------------
199 
200  IMF_EXPORT
201  void breakScanLine (int y, int offset, int length, char c);
202 
203  struct IMF_HIDDEN Data;
204 
205 private:
206  //------------------------------------------------------------
207  // Constructor -- attaches the OutputStreamMutex to the
208  // given one from MultiPartOutputFile. Set the previewPosition
209  // and lineOffsetsPosition which have been acquired from
210  // the constructor of MultiPartOutputFile as well.
211  //------------------------------------------------------------
212  IMF_HIDDEN OutputFile (const OutputPartData* part);
213 
214  OutputFile (const OutputFile&) = delete;
215  OutputFile& operator= (const OutputFile&) = delete;
216  OutputFile (OutputFile&&) = delete;
217  OutputFile& operator= (OutputFile&&) = delete;
218 
219  void initialize (const Header& header);
220 
221  Data* _data;
222 
223  friend class MultiPartOutputFile;
224 };
225 
227 
228 #endif
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
Definition: ImfNamespace.h:83
GLuint GLsizei GLsizei * length
Definition: glcorearb.h:795
GLint y
Definition: glcorearb.h:103
#define IMF_HIDDEN
Definition: ImfExport.h:55
GLintptr offset
Definition: glcorearb.h:665
#define IMF_EXPORT
Definition: ImfExport.h:54
OPENVDB_API void initialize()
Global registration of native Grid, Transform, Metadata and Point attribute types. Also initializes blosc (if enabled).
Definition: logging.h:294
class IMF_EXPORT_TYPE OStream
Definition: ImfForward.h:86
class IMF_EXPORT_TYPE OutputFile
Definition: ImfForward.h:33
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER IMF_EXPORT int globalThreadCount()
LeafData & operator=(const LeafData &)=delete
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
Definition: ImfNamespace.h:80
#define IMF_EXPORT_TYPE
Definition: ImfExport.h:57