public class EXRInputFile extends Object implements AutoCloseable
EXRInputFile
is scanline-based interface that can be used to read
both scanline-based and tiled OpenEXR image files.
Note that this implementation is not synchronized. If multiple
threads access an EXRInputFile
instance and at least one thread
changes the frame buffer of reads pixels, it must be
synchronized externally.
Constructor and Description |
---|
EXRInputFile(EXRFileInputStream is)
A constructor that attaches the new
EXRInputFile to a stream
that has already been opened. |
EXRInputFile(EXRFileInputStream is,
boolean closeStream)
A constructor that attaches the new
EXRInputFile to a stream
that has already been opened and allows to close the input stream along
with the input file. |
EXRInputFile(EXRFileInputStream is,
boolean closeStream,
int numThreads)
A constructor that attaches the new
EXRInputFile to a stream
that has already been opened, using a specific number of threads for I/O
and allows to close the input stream along with the input file. |
EXRInputFile(EXRFileInputStream is,
int numThreads)
A constructor that attaches the new
EXRInputFile to a stream
that has already been opened, using a specific number of threads for I/O. |
EXRInputFile(Path path)
A constructor that opens the file denoted by the given path.
|
EXRInputFile(Path path,
int numThreads)
A constructor that opens the file denoted by the given path, using a
specific number of threads for I/O.
|
Modifier and Type | Method and Description |
---|---|
void |
close()
Closes the underlying file, it one was opened when the instance was
constructed, and destroys the underlying native object.
|
FrameBuffer |
getFrameBuffer()
Returns a reference to the current frame buffer, or
null if it
has not been set yet. |
Header |
getHeader()
Returns a reference to the input file's header.
|
int |
getVersion()
Returns the file format version as read from the file.
|
boolean |
isComplete()
Returns
true if the file is complete. |
boolean |
isOpen()
Returns
true if the underlying input file is open for reading. |
void |
readPixels(int s)
Read pixel data from a single scan line into the current frame buffer.
|
void |
readPixels(int scanLine1,
int scanLine2)
Read pixel data from a scan line range into the current frame buffer.
|
void |
setFrameBuffer(FrameBuffer fBuffer)
Set the current frame buffer by doing a deep copy of the FrameBuffer
input object into the InputFile object.
|
public EXRInputFile(Path path) throws EXRIOException
Calling close
will close the file and destroy the underlying
native object. The image is read using the current number of threads
in the global pool.
Note that even though constructing an input file this way instead of
using an EXRInputStream
may yield higher throughput, there is
a limitation on the number of files that can be simultaneously open.
On Windows 7 this limit is about 500.
path
- the path to be opened for readingEXRIOException
- if an I/O error occursThreading
public EXRInputFile(Path path, int numThreads) throws EXRIOException
Calling close
will close the file and destroy the underlying
native object. numThreads
determines the number of threads that
will be used to read and decompress the file.
Note that even though constructing an input file this way instead of
using an EXRInputStream
may yield higher throughput, there is
a limitation on the number of files that can be simultaneously open.
On Windows 7 this limit is about 500.
path
- the path to be opened for readingnumThreads
- number of native threads to read and decompress the
file, if zero all tasks run on the current thread.EXRIOException
- if an I/O error occursThreading
public EXRInputFile(EXRFileInputStream is) throws EXRIOException
EXRInputFile
to a stream
that has already been opened.
Closing this instance will not close the stream, it will only destroy the underlying native object. The image is read using the current number of threads in the global pool.
Note that by using this constructor the reading performance may be lower than that attained by the constructors which explicitly get a pah to open. This is due to the current implementation which relies on JNI calls to the OpenEXR C++ library.
is
- an already open input streamEXRIOException
- if an I/O error occursThreading
public EXRInputFile(EXRFileInputStream is, int numThreads) throws EXRIOException
EXRInputFile
to a stream
that has already been opened, using a specific number of threads for I/O.
Closing this instance will not close the
stream, it will only destroy the underlying native object.
numThreads
determines the number of threads that will be used to
read and decompress the file.
Note that by using this constructor the reading performance may be lower than that attained by the constructors which explicitly get a path to open. This is due to the current implementation which relies on JNI calls to the OpenEXR C++ library.
is
- an already open input streamnumThreads
- number of native threads to read and decompress the
file, if zero all tasks run on the current thread.EXRIOException
- if an I/O error occursThreading
public EXRInputFile(EXRFileInputStream is, boolean closeStream) throws EXRIOException
EXRInputFile
to a stream
that has already been opened and allows to close the input stream along
with the input file.
If closeStream
is true
closing this instance will
close the input stream as well (if it implements AutoCloseable
),
otherwise the stream will remain open and it will only destroy the
underlying native object. The image is read using the current number of
threads in the global pool.
Note that by using this constructor the reading performance may be lower than that attained by the constructors which explicitly get a path to open. This is due to the current implementation which relies on JNI calls to the OpenEXR C++ library.
is
- an already open input streamcloseStream
- if true
closing this input file will close
the stream as well.EXRIOException
- if an I/O error occursThreading
public EXRInputFile(EXRFileInputStream is, boolean closeStream, int numThreads) throws EXRIOException
EXRInputFile
to a stream
that has already been opened, using a specific number of threads for I/O
and allows to close the input stream along with the input file.
If closeStream
is true
closing this instance will
close the input stream as well (if it implements AutoCloseable
),
otherwise the stream will remain open and it will only destroy the
underlying native object.
numThreads
determines the number of threads that will be used to
read and decompress the file.
Note that by using this constructor the reading performance may be lower than that attained by the constructors which explicitly get a path to open. This is due to the current implementation which relies on JNI calls to the OpenEXR C++ library.
is
- an already open input streamcloseStream
- if true
closing this input file will close
the stream as well.numThreads
- number of native threads to read and decompress the
file, if zero all tasks run on the current thread.EXRIOException
- if an I/O error occursThreading
public void close() throws EXRIOException
close
in interface AutoCloseable
EXRIOException
- if there is an error while closing either the
input file or the underlying streampublic boolean isOpen()
true
if the underlying input file is open for reading.true
if the underlying input file is open for reading.public Header getHeader()
For efficiency this function returns the actual header of this input
file thus callers ought not to modify the returned instance.
In contrast to C++, returning a completely read-only header would require
a lot of changes, including supporting only attributes with all-final
accessible fields and/or read-only aware setters. As a safety feature
the implementation caches the hash code of the header upon opening the
file and compares it against the current header's hash code. It they
do not match it throws an IllegalStateException
.
Because of the validation, clients which want to use the header for
multiple operations should call getHeader
only once and then
use the validated reference.
IllegalStateException
- if the header has been modified externallypublic int getVersion()
public void setFrameBuffer(FrameBuffer fBuffer)
The current frame buffer is the destination for the pixel
data read from the file. The current frame buffer must be
set at least once before readPixels()
is called.
The current frame buffer can be changed after each call
to readPixels()
.
fBuffer
- the source frame bufferIllegalArgumentException
- if the input frame buffer does not
meet the required preconditionsIllegalStateException
- if the file is not open or the header was
modified externallypublic FrameBuffer getFrameBuffer()
null
if it
has not been set yet.
For efficiency this function returns the actual frame buffer of this
input file, thus callers ought not to modify the returned
instance. In contrast to C++, returning a completely read-only frame
buffer would require a lot of changes, including supporting read-only
slices with only-final accessible fields and/or read-only aware setters.
As a safety feature the implementation caches the hash code of the
frame buffer after calling setFrameBuffer
and compares it
against the current frame buffer's hash code. It they
do not match it throws an IllegalStateException
.
Because of the validation, clients which will use the frame buffer for
multiple operations should call getFrameBuffer
only once and then
use the validated reference.
null
if it
has not been set yetIllegalStateException
- if the frame buffer has been modified
externallypublic boolean isComplete()
true
if the file is complete.
isComplete()
returns true
if all pixels in the data
window are present in the input file, or false
if any pixels are
missing. (Another program may still be busy writing the file, or file
writing may have been aborted prematurely.)
true
if the file is completepublic void readPixels(int scanLine1, int scanLine2) throws IndexOutOfBoundsException, IllegalStateException
readPixels(s1,s2)
reads all scan lines with y
coordinates in the interval [min (s1, s2), max (s1, s2)]
from the
file, and stores them in the current frame buffer. Both s1
and s2
must be within the interval
[header().dataWindow().min.y, header().dataWindow().max.y]
The scan lines can be read from the file in random order, and individual scan lines may be skipped or read multiple times. For maximum efficiency, the scan lines should be read in the order in which they were written to the file.
scanLine1
- first scan line to readscanLine2
- last scan line to readIndexOutOfBoundsException
- if either s1
or s2
are outside the interval
[header().dataWindow().min.y, header().dataWindow().max.y]
IllegalStateException
- if the file is not open for reading,
or if the frame buffer has not been set, or if either the header
or the current frame buffer have been modified externallysetFrameBuffer(edu.cornell.graphics.exr.FrameBuffer)
public void readPixels(int s)
This implementation simply calls readPixels(s,s)
s
- scan line to readreadPixels(int, int)