HDK
Main Page
Related Pages
Modules
Namespaces
Classes
Files
Examples
File List
File Members
All
Classes
Namespaces
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
ImfInputFile.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_INPUT_FILE_H
7
#define INCLUDED_IMF_INPUT_FILE_H
8
9
//-----------------------------------------------------------------------------
10
//
11
// class InputFile -- a scanline-based interface that can be used
12
// to read both scanline-based and tiled OpenEXR image files.
13
//
14
//-----------------------------------------------------------------------------
15
16
#include "
ImfForward.h
"
17
18
#include "
ImfThreading.h
"
19
20
#include "
ImfContext.h
"
21
22
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
23
24
class
TiledInputFile
;
25
26
/// \brief Provides generic access to read an image from an EXR file
27
///
28
/// There are a suite of classes for accessing image data, depending
29
/// on the level of complexity your application demands. This one is
30
/// perhaps a good starting point. There is a simpler one in \sa
31
/// RgbaInputFile, but that has very noted limitations of only being
32
/// for a 16-bit half, RGBA image. This class gives access to
33
/// arbitrary channels and data type outputs. It also will convert a
34
/// tiled image into a "normal" image, and simplify access if you only
35
/// want the first part, first image of a file.
36
///
37
/// If you will be accessing tiles (say for a renderer), working with
38
/// multi-part images, or reading deep data there are other classes
39
/// which provide API for handling that complexity more efficiently:
40
///
41
/// MultiPartInputFile
42
/// can be constructed but not directly accessible
43
/// - InputPart (the part-based class corresponding to this class)
44
/// - TiledInputPart
45
/// - DeepTiledInputPart
46
/// - DeepScanlineInputPart
47
/// - ScanlineInputPart [[[ NEW, but for consistency ]]]
48
/// TiledInputFile
49
/// DeepScanLineInputFile
50
/// DeepTiledInputFile
51
/// ScanLineInputFile
52
///
53
/// Of these, InputFile provide somewhat of a barrier to knowing what
54
/// the file actually contains, such that it allows you to read a file
55
/// as if it is scanlines, even if it is actually tiled under the
56
/// covers. Similar, a deep file is automatically composited for the
57
/// user. If a multi-part file is opened, the first part will be
58
/// provided.
59
///
60
/// For most code, it is suggested to use MultiPartInputFile and the
61
/// API provided by the relevant part classes, but if only a simple
62
/// API is needed, InputFile will certainly hide much of the
63
/// complexity.
64
class
IMF_EXPORT_TYPE
InputFile
65
{
66
public
:
67
//-------------------------------------------------------------
68
// A constructor that attaches the new InputFile object to a
69
// file that has already been opened. Destroying the InputFile
70
// object will not close the file.
71
//
72
// numThreads determines the number of threads that will be
73
// used to read the file (see ImfThreading.h).
74
//-------------------------------------------------------------
75
76
IMF_EXPORT
77
InputFile
(
78
OPENEXR_IMF_INTERNAL_NAMESPACE::IStream
& is,
79
int
numThreads =
globalThreadCount
());
80
81
//-----------------------------------------------------------
82
// A constructor that opens the file with the specified name.
83
// Destroying the InputFile object will close the file.
84
//
85
// numThreads determines the number of threads that will be
86
// used to read the file (see ImfThreading.h).
87
//-----------------------------------------------------------
88
IMF_EXPORT
89
InputFile
(
const
char
filename
[],
int
numThreads =
globalThreadCount
());
90
91
//-----------------------------------------------------------
92
// A constructor that opens the file with the specified name
93
// and context initialization routines
94
// Destroying the InputFile object will close the file.
95
//-----------------------------------------------------------
96
IMF_EXPORT
97
InputFile
(
98
const
char
* filename,
99
const
ContextInitializer
& ctxtinit,
100
int
numThreads =
globalThreadCount
());
101
102
//------------------------
103
// Access to the file name
104
//------------------------
105
106
IMF_EXPORT
107
const
char
* fileName ()
const
;
108
109
//--------------------------
110
// Access to the file header
111
//--------------------------
112
113
IMF_EXPORT
114
const
Header
& header ()
const
;
115
116
//----------------------------------
117
// Access to the file format version
118
//----------------------------------
119
120
IMF_EXPORT
121
int
version
()
const
;
122
123
//-----------------------------------------------------------
124
// Set the current frame buffer -- copies the FrameBuffer
125
// object into the InputFile object.
126
//
127
// The current frame buffer is the destination for the pixel
128
// data read from the file. The current frame buffer must be
129
// set at least once before readPixels() is called.
130
// The current frame buffer can be changed after each call
131
// to readPixels().
132
//-----------------------------------------------------------
133
134
IMF_EXPORT
135
void
setFrameBuffer (
const
FrameBuffer
& frameBuffer);
136
137
//-----------------------------------
138
// Access to the current frame buffer
139
//-----------------------------------
140
141
IMF_EXPORT
142
const
FrameBuffer
& frameBuffer ()
const
;
143
144
//---------------------------------------------------------------
145
// Check if the file is complete:
146
//
147
// isComplete() returns true if all pixels in the data window are
148
// present in the input file, or false if any pixels are missing.
149
// (Another program may still be busy writing the file, or file
150
// writing may have been aborted prematurely.)
151
//---------------------------------------------------------------
152
153
IMF_EXPORT
154
bool
isComplete ()
const
;
155
156
//---------------------------------------------------------------
157
// Check if SSE optimization is enabled
158
//
159
// Call after setFrameBuffer() to query whether optimized file decoding
160
// is available - decode times will be faster if returns true
161
//
162
// Optimization depends on:
163
// the file type (only scanline data is supported),
164
// the framebuffer channels (RGB/RGBA mono or stereo)
165
// the framebuffer channel types (all channels half-float format only)
166
// the file channels (RGB/RGBA mono or stereo)
167
// the file channel types (all channel half-float format only)
168
// whether SSE2 instruction support was detected at compile time
169
//
170
// Calling isOptimizationEnabled before setFrameBuffer will throw an exception
171
//
172
//---------------------------------------------------------------
173
174
OPENEXR_DEPRECATED
(
"No longer meaningful"
)
175
IMF_EXPORT
176
bool
isOptimizationEnabled ()
const
;
177
178
//---------------------------------------------------------------
179
// Read pixel data:
180
//
181
// readPixels(s1,s2) reads all scan lines with y coordinates
182
// in the interval [min (s1, s2), max (s1, s2)] from the file,
183
// and stores them in the current frame buffer.
184
//
185
// Both s1 and s2 must be within the interval
186
// [header().dataWindow().min.y, header().dataWindow().max.y]
187
//
188
// The scan lines can be read from the file in random order, and
189
// individual scan lines may be skipped or read multiple times.
190
// For maximum efficiency, the scan lines should be read in the
191
// order in which they were written to the file.
192
//
193
// readPixels(s) calls readPixels(s,s).
194
//
195
//---------------------------------------------------------------
196
197
IMF_EXPORT
198
void
readPixels (
int
scanLine1,
int
scanLine2);
199
200
IMF_EXPORT
201
void
readPixels (
int
scanLine);
202
203
//----------------------------------------------
204
// Combines the setFrameBuffer and readPixels into a singular
205
// call. This does more than that in that it can, with the right
206
// conditions, not require a lock on the file, such that multiple
207
// (external to OpenEXR) threads can read at the same time on
208
// different framebuffers
209
//
210
// NB: if the underlying file is deep or tiled, that requires
211
// translation, so will not do the pass through, but will behave
212
// in a threadsafe manner (where the only way that was possible
213
// before was to have a larger framebuffer, set the framebuffer
214
// once, then call readPixels by the external threads, although
215
// that occured with a mutex and so the reads were serialized.
216
// There are reasons why that might still be serialized, such as a
217
// non-threadable stream.
218
//----------------------------------------------
219
220
IMF_EXPORT
221
void
readPixels (
222
const
FrameBuffer
& frameBuffer,
int
scanLine1,
int
scanLine2);
223
224
//----------------------------------------------
225
// Read a block of raw pixel data from the file,
226
// without uncompressing it (this function is
227
// used to implement OutputFile::copyPixels()).
228
//----------------------------------------------
229
230
IMF_EXPORT
231
void
rawPixelData (
232
int
firstScanLine,
const
char
*& pixelData,
int
& pixelDataSize);
233
234
//----------------------------------------------
235
// Read a scanline's worth of raw pixel data
236
// from the file, without uncompressing it, and
237
// store in an external buffer, pixelData.
238
// pixelData should be pre-allocated with space
239
// for pixelDataSize chars.
240
//
241
// This function can be used to separate the
242
// reading of a raw scan line from the
243
// decompression of that scan line, for
244
// example to allow multiple scan lines to be
245
// decompressed in parallel by an application's
246
// own threads, where it is not convenient to
247
// use the threading within the library.
248
//----------------------------------------------
249
250
IMF_EXPORT
251
void
rawPixelDataToBuffer (
252
int
scanLine,
char
* pixelData,
int
& pixelDataSize)
const
;
253
254
//--------------------------------------------------
255
// Read a tile of raw pixel data from the file,
256
// without uncompressing it (this function is
257
// used to implement TiledOutputFile::copyPixels()).
258
//--------------------------------------------------
259
260
IMF_EXPORT
261
void
rawTileData (
262
int
& dx,
263
int
& dy,
264
int
& lx,
265
int
& ly,
266
const
char
*& pixelData,
267
int
& pixelDataSize);
268
269
private
:
270
IMF_HIDDEN
void
initialize
(
void
);
271
272
// TODO: Remove these once MultiPartInputFile is converted
273
IMF_HIDDEN
InputFile
(InputPartData* part);
274
friend
class
MultiPartInputFile
;
275
276
// TODO: Remove these once TiledOutputFile is converted
277
IMF_HIDDEN
TiledInputFile
& asTiledInput (
void
)
const
;
278
friend
class
TiledOutputFile
;
279
280
Context
_ctxt;
281
struct
Data;
282
std::shared_ptr<Data> _data;
283
};
284
285
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
286
287
#endif
GT_Names::filename
GT_API const UT_StringHolder filename
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
Definition:
ImfNamespace.h:83
ImfThreading.h
InputFile
class IMF_EXPORT_TYPE InputFile
Definition:
ImfForward.h:36
TiledInputFile
Definition:
ImfTiledInputFile.h:26
ImfContext.h
InputFile
Provides generic access to read an image from an EXR file.
Definition:
ImfInputFile.h:64
IMF_HIDDEN
#define IMF_HIDDEN
Definition:
ImfExport.h:55
ContextInitializer
ContextInitializer provides a basic type to initialize a Context with.
Definition:
ImfContextInit.h:20
FrameBuffer
Definition:
ImfFrameBuffer.h:153
MultiPartInputFile
TODO: Document this.
Definition:
ImfMultiPartInputFile.h:20
OPENEXR_DEPRECATED
#define OPENEXR_DEPRECATED(msg)
Definition:
OpenEXRConfig.h:178
IMF_EXPORT
#define IMF_EXPORT
Definition:
ImfExport.h:54
openvdb::OPENVDB_VERSION_NAME::initialize
OPENVDB_API void initialize()
Global registration of native Grid, Transform, Metadata and Point attribute types. Also initializes blosc (if enabled).
Definition:
logging.h:294
ImfForward.h
GT_Names::version
GT_API const UT_StringHolder version
globalThreadCount
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER IMF_EXPORT int globalThreadCount()
Context
Context provides a wrapper around the Core library context object.
Definition:
ImfContext.h:30
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
Definition:
ImfNamespace.h:80
Header
Definition:
ImfHeader.h:36
TiledOutputFile
Definition:
ImfTiledOutputFile.h:27
IMF_EXPORT_TYPE
#define IMF_EXPORT_TYPE
Definition:
ImfExport.h:57
IStream
class IMF_EXPORT_TYPE IStream
Definition:
ImfForward.h:87
OpenEXR
ImfInputFile.h
Generated on Wed Aug 27 2025 03:06:53 for HDK by
1.8.6