///////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2014, Industrial Light & Magic, a division of Lucas
// Digital Ltd. LLC
//
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
// * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
// * Neither the name of Industrial Light & Magic nor the names of
// its contributors may be used to endorse or promote products derived
// from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
///////////////////////////////////////////////////////////////////////////
#ifndef INCLUDED_IMF_SAMPLE_COUNT_CHANNEL_H
#define INCLUDED_IMF_SAMPLE_COUNT_CHANNEL_H
//----------------------------------------------------------------------------
//
// class SampleCountChannel
//
// For an explanation of images, levels and channels,
// see the comments in header file Image.h.
//
//----------------------------------------------------------------------------
#include "ImfImageChannel.h"
#include "ImfExport.h"
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
class DeepImageLevel;
//
// Sample count channel for a deep image level:
//
// Each deep image level has a number of samples channel. For each
// pixel location (x,y) within the data window of the level, the sample
// count channel stores a single integer, n(x,y). A deep channel, c,
// in the level as the sample count channel stores n(x,y) samples at
// location (x,y) if
//
// x % c.xSampling() == 0 and y % c.ySampling() == 0.
//
// The deep channel stores no samples at location (x,y) if
//
// x % c.xSampling() != 0 or y % c.ySampling() != 0,
//
class IMF_EXPORT SampleCountChannel : public ImageChannel
{
public:
//
// The OpenEXR pixel type of this channel (HALF, FLOAT or UINT).
//
virtual PixelType pixelType () const;
//
// Construct an OpenEXR frame buffer slice for this channel.
// This function is needed reading an image from an OpenEXR
// file and for saving an image in an OpenEXR file.
//
Slice slice () const;
//
// Access to the image level to which this channel belongs.
//
DeepImageLevel & deepLevel ();
const DeepImageLevel & deepLevel () const;
//
// Access to n(x,y), without bounds checking. Accessing a location
// outside the data window of the image level results in undefined
// behavior.
//
const unsigned int & operator () (int x, int y) const;
//
// Access to n(x,y), with bounds checking. Accessing a location outside
// the data window of the image level throws an Iex::ArgExc exception.
//
const unsigned int & at (int x, int y) const;
//
// Faster access to n(x,y) for all pixels in a single horizontal row of
// the channel. Rows are numbered from 0 to pixelsPerColumn()-1, and
// each row contains pixelsPerRow() values.
// Access is not bounds checked; accessing out of bounds rows or pixels
// results in undefined behavior.
//
const unsigned int * row (int r) const;
//
// Change the sample counts in one or more pixels:
//
// set(x,y,m) sets n(x,y) to m.
//
// set(r,m) sets n(x,y) for all pixels in row r according to the
// values in array m. The array must contain pixelsPerRow()
// entries, and the row number must be in the range from 0
// to pixelsPerColumn()-1.
//
// clear() sets n(x,y) to 0 for all pixels within the data window
// of the level.
//
// If the sample count for a pixel is increased, then new samples are
// appended at the end of the sample list of each deep channel. The
// new samples are initialized to zero. If the sample count in a pixel
// is decreased, then sample list of each deep channel is truncated by
// discarding samples at the end of the list.
//
// Access is bounds-checked; attempting to set the number of samples of
// a pixel outside the data window throws an Iex::ArgExc exception.
//
// Memory allocation for the sample lists is not particularly clever;
// repeatedly increasing and decreasing the number of samples in the
// pixels of a level is likely to result in serious memory fragmentation.
//
// Setting the number of samples for one or more pixels may cause the
// program to run out of memory. If this happens, the image is resized
// to zero by zero pixels and an exception is thrown. Note that the
// resizing operation deletes this sample count channel and the image
// level to which it belongs.
//
void set(int x, int y, unsigned int newNumSamples);
void set(int r, unsigned int newNumSamples[]);
void clear();
//
// OpenEXR file reading support / make sample counts editable:
//
// beginEdit() frees all memory that has been allocated for samples
// in the deep channels, and returns a pointer to an
// array of pixelsPerRow() by pixelsPerColumn() sample
// counts in row-major order.
//
// After beginEdit() returns, application code is
// free to change the values in the sample count array.
// In particular, the application can fill the array by
// reading the sample counts from an OpenEXR file.
//
// However, since memory for the samples in the deep
// channels has been freed, attempting to access any
// sample in a deep channel results in undefined
// behavior, most likely a program crash.
//
// endEdit() allocates new memory for all samples in the deep
// channels of the layer, according to the current
// sample counts, and sets the samples to zero.
//
// Application code must take make sure that each call to beginEdit()
// is followed by a corresponding endEdit() call, even if an
// exception occurs while the sample counts are acessed. In order to
// do that, application code may want to create a temporary Edit
// object instead of calling beginEdit() and endEdit() directly.
//
// Setting the number of samples for all pixels in the image may
// cause the program to run out of memory. If this happens, the image
// is resized to zero by zero pixels and an exception is thrown.
// Note that the resizing operation deletes this sample count channel
// and the image level to which it belongs.
//
unsigned int * beginEdit();
void endEdit();
class Edit
{
public:
//
// Constructor calls level->beginEdit(),
// destructor calls level->endEdit().
//
Edit (SampleCountChannel& level);
~Edit ();
//
// Access to the writable sample count array.
//
unsigned int * sampleCounts () const;
private:
SampleCountChannel & _channel;
unsigned int * _sampleCounts;
};
//
// Functions that support the implementation of deep image channels.
//
const unsigned int * numSamples () const;
const unsigned int * sampleListSizes () const;
const size_t * sampleListPositions () const;
size_t sampleBufferSize () const;
private:
friend class DeepImageLevel;
//
// The constructor and destructor are not public because
// image channels exist only as parts of a deep image level.
//
SampleCountChannel (DeepImageLevel &level);
virtual ~SampleCountChannel();
virtual void resize ();
void resetBasePointer ();
unsigned int * _numSamples; // Array of per-pixel sample counts
unsigned int * _base; // Base pointer for faster access
// to entries in _numSamples
unsigned int * _sampleListSizes; // Array of allocated sizes of
// per-pixel sample lists
size_t * _sampleListPositions; // Array of positions of per-pixel
// sample lists within sample list
// buffer
size_t _totalNumSamples; // Sum of all entries in the
// _numSamples array
size_t _totalSamplesOccupied; // Total number of samples within
// sample list buffer that have
// either been allocated for sample
// lists or lost to fragmentation
size_t _sampleBufferSize; // Size of the sample list buffer.
};
//-----------------------------------------------------------------------------
// Implementation of templates and inline functions
//-----------------------------------------------------------------------------
inline
SampleCountChannel::Edit::Edit (SampleCountChannel &channel):
_channel (channel),
_sampleCounts (channel.beginEdit())
{
// empty
}
inline
SampleCountChannel::Edit::~Edit ()
{
_channel.endEdit();
}
inline unsigned int *
SampleCountChannel::Edit::sampleCounts () const
{
return _sampleCounts;
}
inline const unsigned int *
SampleCountChannel::numSamples () const
{
return _numSamples;
}
inline const unsigned int *
SampleCountChannel::sampleListSizes () const
{
return _sampleListSizes;
}
inline const size_t *
SampleCountChannel::sampleListPositions () const
{
return _sampleListPositions;
}
inline size_t
SampleCountChannel::sampleBufferSize () const
{
return _sampleBufferSize;
}
inline const unsigned int &
SampleCountChannel::operator () (int x, int y) const
{
return _base[y * pixelsPerRow() + x];
}
inline const unsigned int &
SampleCountChannel::at (int x, int y) const
{
boundsCheck (x, y);
return _base[y * pixelsPerRow() + x];
}
inline const unsigned int *
SampleCountChannel::row (int n) const
{
return _base + n * pixelsPerRow();
}
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
#endif