imftiledoutputfile.h

image converter source code

    //
    //	return value is:
    //      (levelWidth(lx) + tileXSize() - 1) / tileXSize()
    //
    //
    // numYTiles(ly) returns the number of tiles in y direction
    // that cover a level with level number (*, ly), where * is
    // any number.
    //
    //	return value is:
    //      (levelHeight(ly) + tileXSize() - 1) / tileXSize()
    //
    //----------------------------------------------------------

    int			numXTiles (int lx = 0) const;
    int			numYTiles (int ly = 0) const;


    //---------------------------------------------------------
    // Level pixel ranges:
    //
    // dataWindowForLevel(lx, ly) returns a 2-dimensional
    // region of valid pixel coordinates for a level with
    // level number (lx, ly)
    //
    //	return value is a Box2i with min value:
    //      (dataWindow.min.x, dataWindow.min.y)
    //
    //	and max value:
    //      (dataWindow.min.x + levelWidth(lx) - 1,
    //       dataWindow.min.y + levelHeight(ly) - 1)
    //
    // dataWindowForLevel(level) is a convenience function used
    // for ONE_LEVEL and MIPMAP_LEVELS files.  It returns
    // dataWindowForLevel(level, level).
    //
    //---------------------------------------------------------

    Imath::Box2i	dataWindowForLevel (int l = 0) const;
    Imath::Box2i	dataWindowForLevel (int lx, int ly) const;


    //-------------------------------------------------------------------
    // Tile pixel ranges:
    //
    // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional
    // region of valid pixel coordinates for a tile with tile coordinates
    // (dx,dy) and level number (lx, ly).
    //
    //	return value is a Box2i with min value:
    //      (dataWindow.min.x + dx * tileXSize(),
    //       dataWindow.min.y + dy * tileYSize())
    //
    //	and max value:
    //      (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
    //       dataWindow.min.y + (dy + 1) * tileYSize() - 1)
    //
    // dataWindowForTile(dx, dy, level) is a convenience function
    // used for ONE_LEVEL and MIPMAP_LEVELS files.  It returns
    // dataWindowForTile(dx, dy, level, level).
    //
    //-------------------------------------------------------------------

    Imath::Box2i	dataWindowForTile (int dx, int dy,
					   int l = 0) const;

    Imath::Box2i	dataWindowForTile (int dx, int dy,
					   int lx, int ly) const;

    //------------------------------------------------------------------
    // Write pixel data:
    //
    // writeTile(dx, dy, lx, ly) writes the tile with tile
    // coordinates (dx, dy), and level number (lx, ly) to
    // the file.
    //
    //   dx must lie in the interval [0, numXTiles(lx) - 1]
    //   dy must lie in the interval [0, numYTiles(ly) - 1]
    //
    //   lx must lie in the interval [0, numXLevels() - 1]
    //   ly must lie in the inverval [0, numYLevels() - 1]
    //
    // writeTile(dx, dy, level) is a convenience function
    // used for ONE_LEVEL and MIPMAP_LEVEL files.  It calls
    // writeTile(dx, dy, level, level).
    //
    // The two writeTiles(dx1, dx2, dy1, dy2, ...) functions allow
    // writing multiple tiles at once.  If multi-threading is used
    // multiple tiles are written concurrently.  The tile coordinates,
    // dx1, dx2 and dy1, dy2, specify inclusive ranges of tile
    // coordinates.  It is valid for dx1 < dx2 or dy1 < dy2; the
    // tiles are always written in the order specified by the line
    // order attribute.  Hence, it is not possible to specify an
    // "invalid" or empty tile range.
    //
    // Pixels that are outside the pixel coordinate range for the tile's
    // level, are never accessed by writeTile().
    //
    // Each tile in the file must be written exactly once.
    //
    // The file's line order attribute determines the order of the tiles
    // in the file:
    //
    //	 INCREASING_Y	In the file, the tiles for each level are stored
    //	 		in a contiguous block.  The levels are ordered
    //	 		like this:
    //
    //			    (0, 0)   (1, 0)   ... (nx-1, 0) 
    //			    (0, 1)   (1, 1)   ... (nx-1, 1) 
    //			     ...
    //			    (0,ny-1) (1,ny-1) ... (nx-1,ny-1) 
    //
    //			where nx = numXLevels(), and ny = numYLevels().
    //			In an individual level, (lx, ly), the tiles
    //			are stored in the following order:
    //
    //			    (0, 0)   (1, 0)   ... (tx-1, 0)
    //			    (0, 1)   (1, 1)   ... (tx-1, 1)
    //			     ...
    //			    (0,ty-1) (1,ty-1) ... (tx-1,ty-1)
    //
    //			where tx = numXTiles(lx),
    //			and   ty = numYTiles(ly).
    //
    //	 DECREASING_Y   As for INCREASING_Y, the tiles for each level
    //			are stored in a contiguous block.  The levels
    //			are ordered the same way as for INCREASING_Y,
    //			but within an individual level, the tiles
    //			are stored in this order:
    //
    //			    (0,ty-1) (1,ty-1) ... (tx-1,ty-1)
    //			     ...
    //			    (0, 1)   (1, 1)   ... (tx-1, 1)
    //			    (0, 0)   (1, 0)   ... (tx-1, 0)
    //
    //
    //	 RANDOM_Y	The order of the calls to writeTile() determines
    //	 		the order of the tiles in the file.
    //
    //------------------------------------------------------------------

    void		writeTile  (int dx, int dy, int l = 0);
    void		writeTile  (int dx, int dy, int lx, int ly);

    void		writeTiles (int dx1, int dx2, int dy1, int dy2,
                                    int lx, int ly);

    void		writeTiles (int dx1, int dx2, int dy1, int dy2,
                                    int l = 0);


    //------------------------------------------------------------------
    // Shortcut to copy all pixels from a TiledInputFile into this file,
    // without uncompressing and then recompressing the pixel data.
    // This file's header must be compatible with the TiledInputFile's
    // header:  The two header's "dataWindow", "compression",
    // "lineOrder", "channels", and "tiles" attributes must be the same.
    //------------------------------------------------------------------
    
    void		copyPixels (TiledInputFile &in);
    

    //------------------------------------------------------------------
    // Shortcut to copy all pixels from an InputFile into this file,
    // without uncompressing and then recompressing the pixel data.
    // This file's header must be compatible with the InputFile's
    // header:  The two header's "dataWindow", "compression",
    // "lineOrder", "channels", and "tiles" attributes must be the same.
    //
    // To use this function, the InputFile must be tiled.
    //------------------------------------------------------------------
    
    void		copyPixels (InputFile &in);


    //--------------------------------------------------------------
    // Updating the preview image:
    //
    // updatePreviewImage() supplies a new set of pixels for the
    // preview image attribute in the file's header.  If the header
    // does not contain a preview image, updatePreviewImage() throws
    // an Iex::LogicExc.
    //
    // Note: updatePreviewImage() is necessary because images are
    // often stored in a file incrementally, a few tiles at a time,
    // while the image is being generated.  Since the preview image
    // is an attribute in the file's header, it gets stored in the
    // file as soon as the file is opened, but we may not know what
    // the preview image should look like until we have written the
    // last tile of the main image.
    //
    //--------------------------------------------------------------

    void		updatePreviewImage (const PreviewRgba newPixels[]);


    //-------------------------------------------------------------
    // Break a tile -- for testing and debugging only:
    // 
    // breakTile(dx,dy,lx,ly,p,n,c) introduces an error into the
    // output file by writing n copies of character c, starting
    // p bytes from the beginning of the tile with tile coordinates
    // (dx, dy) and level number (lx, ly).
    //
    // Warning: Calling this function usually results in a broken
    // image file.  The file or parts of it may not be readable,
    // or the file may contain bad data.
    //
    //-------------------------------------------------------------

    void		breakTile  (int dx, int dy,
				    int lx, int ly,
				    int offset,
				    int length,
				    char c);
    struct Data;

  private:

    TiledOutputFile (const TiledOutputFile &);		    // not implemented
    TiledOutputFile & operator = (const TiledOutputFile &); // not implemented

    void		initialize (const Header &header);

    bool		isValidTile (int dx, int dy,
				     int lx, int ly) const;

    size_t		bytesPerLineForTile (int dx, int dy,
					     int lx, int ly) const;

    Data *		_data;
};


} // namespace Imf

#endif