imftiledoutputfile.h

image converter source code

///////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2004, 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_TILED_OUTPUT_FILE_H
#define INCLUDED_IMF_TILED_OUTPUT_FILE_H

//-----------------------------------------------------------------------------
//
//	class TiledOutputFile
//
//-----------------------------------------------------------------------------

#include <ImfHeader.h>
#include <ImfFrameBuffer.h>
#include "ImathBox.h"
#include <ImfTileDescription.h>
#include <ImfThreading.h>

namespace Imf {

class TiledInputFile;
class InputFile;
struct PreviewRgba;


class TiledOutputFile
{
  public:

    //-------------------------------------------------------------------
    // A constructor that opens the file with the specified name, and
    // writes the file header.  The file header is also copied into the
    // TiledOutputFile object, and can later be accessed via the header()
    // method.
    //
    // Destroying TiledOutputFile constructed with this constructor
    // automatically closes the corresponding files.
    //
    // The header must contain a TileDescriptionAttribute called "tiles".
    //
    // The x and y subsampling factors for all image channels must be 1;
    // subsampling is not supported.
    //
    // Tiles can be written to the file in arbitrary order.  The line
    // order attribute can be used to cause the tiles to be sorted in
    // the file.  When the file is read later, reading the tiles in the
    // same order as they are in the file tends to be significantly
    // faster than reading the tiles in random order (see writeTile,
    // below).
    //-------------------------------------------------------------------
    
    TiledOutputFile (const char fileName[],
		     const Header &header,
                     int numThreads = globalThreadCount ());


    // ----------------------------------------------------------------
    // A constructor that attaches the new TiledOutputFile object to
    // a file that has already been opened.  Destroying TiledOutputFile
    // objects constructed with this constructor does not automatically
    // close the corresponding files.
    // ----------------------------------------------------------------

    TiledOutputFile (OStream &os,
		     const Header &header,
                     int numThreads = globalThreadCount ());


    //-----------------------------------------------------
    // Destructor
    //
    // Destroying a TiledOutputFile object before all tiles
    // have been written results in an incomplete file.
    //-----------------------------------------------------
    
    virtual ~TiledOutputFile ();


    //------------------------
    // Access to the file name
    //------------------------
    
    const char *	fileName () const;


    //--------------------------
    // Access to the file header
    //--------------------------
    
    const Header &	header () const;


    //-------------------------------------------------------
    // Set the current frame buffer -- copies the FrameBuffer
    // object into the TiledOutputFile object.
    //
    // The current frame buffer is the source of the pixel
    // data written to the file.  The current frame buffer
    // must be set at least once before writeTile() is
    // called.  The current frame buffer can be changed
    // after each call to writeTile().
    //-------------------------------------------------------
    
    void		setFrameBuffer (const FrameBuffer &frameBuffer);


    //-----------------------------------
    // Access to the current frame buffer
    //-----------------------------------
    
    const FrameBuffer &	frameBuffer () const;


    //-------------------
    // Utility functions:
    //-------------------

    //---------------------------------------------------------
    // Multiresolution mode and tile size:
    // The following functions return the xSize, ySize and mode
    // fields of the file header's TileDescriptionAttribute.
    //---------------------------------------------------------

    unsigned int	tileXSize () const;
    unsigned int	tileYSize () const;
    LevelMode		levelMode () const;
    LevelRoundingMode	levelRoundingMode () const;


    //--------------------------------------------------------------------
    // Number of levels:
    //
    // numXLevels() returns the file's number of levels in x direction.
    //
    //	if levelMode() == ONE_LEVEL:
    //      return value is: 1
    //
    //	if levelMode() == MIPMAP_LEVELS:
    //      return value is: rfunc (log (max (w, h)) / log (2)) + 1
    //
    //	if levelMode() == RIPMAP_LEVELS:
    //      return value is: rfunc (log (w) / log (2)) + 1
    //
    //	where
    //	    w is the width of the image's data window,  max.x - min.x + 1,
    //	    y is the height of the image's data window, max.y - min.y + 1,
    //	    and rfunc(x) is either floor(x), or ceil(x), depending on
    //	    whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
    //
    // numYLevels() returns the file's number of levels in y direction.
    //
    //	if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
    //      return value is the same as for numXLevels()
    //
    //	if levelMode() == RIPMAP_LEVELS:
    //      return value is: rfunc (log (h) / log (2)) + 1
    //
    //
    // numLevels() is a convenience function for use with MIPMAP_LEVELS
    // files.
    //
    //	if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
    //      return value is the same as for numXLevels()
    //
    //	if levelMode() == RIPMAP_LEVELS:
    //      an Iex::LogicExc exception is thrown
    //
    // isValidLevel(lx, ly) returns true if the file contains 
    // a level with level number (lx, ly), false if not.
    //
    //--------------------------------------------------------------------

    int			numLevels () const;
    int			numXLevels () const;
    int			numYLevels () const;
    bool		isValidLevel (int lx, int ly) const;


    //---------------------------------------------------------
    // Dimensions of a level:
    //
    // levelWidth(lx) returns the width of a level with level
    // number (lx, *), where * is any number.
    //
    //	return value is:
    //      max (1, rfunc (w / pow (2, lx)))
    //
    //
    // levelHeight(ly) returns the height of a level with level
    // number (*, ly), where * is any number.
    //
    //	return value is:
    //      max (1, rfunc (h / pow (2, ly)))
    //
    //---------------------------------------------------------

    int			levelWidth  (int lx) const;
    int			levelHeight (int ly) const;


    //----------------------------------------------------------
    // Number of tiles:
    //
    // numXTiles(lx) returns the number of tiles in x direction
    // that cover a level with level number (lx, *), where * is
    // any number.