ImfMisc.h

Go to the documentation of this file.

//
// SPDX-License-Identifier: BSD-3-Clause
// Copyright (c) Contributors to the OpenEXR Project.
//

#ifndef INCLUDED_IMF_MISC_H
#define INCLUDED_IMF_MISC_H

//-----------------------------------------------------------------------------
//
//      Miscellaneous helper functions for OpenEXR image file I/O
//
//-----------------------------------------------------------------------------

#include "ImfForward.h"

#include "ImfArray.h"
#include "ImfCompressor.h"
#include "ImfPixelType.h"

#include <cstddef>
#include <vector>

OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER

//
// Return the size of a single value of the indicated type,
// in the machine's native format.
//

IMF_EXPORT
int pixelTypeSize (PixelType type);

//
// Return the number of samples a channel with subsampling rate
// s has in the interval [a, b].  For example, a channel with
// subsampling rate 2 (and samples at 0, 2, 4, 6, 8, etc.) has
// 2 samples in the interval [1, 5] and three samples in the
// interval [2, 6].
//

IMF_EXPORT
int numSamples (int s, int a, int b);

//
// Build a table that lists, for each scanline in a file's
// data window, how many bytes are required to store all
// pixels in all channels in that scanline (assuming that
// the pixel data are tightly packed).
//

IMF_EXPORT
size_t
bytesPerLineTable (const Header& header, std::vector<size_t>& bytesPerLine);

//
// Get the sample count for pixel (x, y) using the array base
// pointer, xStride and yStride.
//

inline int&
sampleCount (char* base, int xStride, int yStride, int x, int y)
{
    char* ptr    = base + y * ptrdiff_t (yStride) + x * ptrdiff_t (xStride);
    int*  intPtr = (int*) ptr;

    return *intPtr;
}

inline const int&
sampleCount (const char* base, int xStride, int yStride, int x, int y)
{
    const char* ptr = base + y * ptrdiff_t (yStride) + x * ptrdiff_t (xStride);
    int*        intPtr = (int*) ptr;

    return *intPtr;
}

//
// Build a table that lists, for each scanline in a DEEP file's
// data window, how many bytes are required to store all
// pixels in all channels in scanlines ranged in [minY, maxY]
// (assuming that the pixel data are tightly packed).
//

IMF_EXPORT
size_t bytesPerDeepLineTable (
    const Header&        header,
    int                  minY,
    int                  maxY,
    const char*          base,
    int                  xStride,
    int                  yStride,
    std::vector<size_t>& bytesPerLine);

//
// Build a table that lists, for each scanline in a DEEP file's
// data window, how many bytes are required to store all
// pixels in all channels in every scanline (assuming that
// the pixel data are tightly packed).
//

IMF_EXPORT
size_t bytesPerDeepLineTable (
    const Header&        header,
    char*                base,
    int                  xStride,
    int                  yStride,
    std::vector<size_t>& bytesPerLine);

//
// For scanline-based files, pixels are read or written in
// in multi-scanline blocks.  Internally, class OutputFile
// and class ScanLineInputFile store a block of scan lines
// in a "line buffer".  Function offsetInLineBufferTable()
// builds a table that lists, scanlines within range
// [scanline1, scanline2], the location of the pixel data
// for the scanline relative to the beginning of the line buffer,
// where scanline1 = 0 represents the first line in the DATA WINDOW.
// The one without specifying the range will make scanline1 = 0
// and scanline2 = bytesPerLine.size().
//

IMF_EXPORT
void offsetInLineBufferTable (
    const std::vector<size_t>& bytesPerLine,
    int                        scanline1,
    int                        scanline2,
    int                        linesInLineBuffer,
    std::vector<size_t>&       offsetInLineBuffer);

IMF_EXPORT
void offsetInLineBufferTable (
    const std::vector<size_t>& bytesPerLine,
    int                        linesInLineBuffer,
    std::vector<size_t>&       offsetInLineBuffer);

//
// For a scanline-based file, compute the range of scanlines
// that occupy the same line buffer as a given scanline, y.
// (minY is the minimum y coordinate of the file's data window.)
//

IMF_EXPORT int lineBufferMinY (int y, int minY, int linesInLineBuffer);
IMF_EXPORT int lineBufferMaxY (int y, int minY, int linesInLineBuffer);

//
// Return a compressor's data format (Compressor::NATIVE or Compressor::XDR).
// If compressor is 0, return Compressor::XDR.
//

IMF_EXPORT
Compressor::Format defaultFormat (Compressor* compressor);

//
// Return the number of scan lines a compressor wants to compress
// or uncompress at once.  If compressor is 0, return 1.
//

IMF_EXPORT
int numLinesInBuffer (Compressor* compressor);

//
// Copy a single channel of a horizontal row of pixels from an
// input file's internal line buffer or tile buffer into a
// frame buffer slice.  If necessary, perform on-the-fly data
// type conversion.
//
//    readPtr           initially points to the beginning of the
//                      data in the line or tile buffer. readPtr
//                      is advanced as the pixel data are copied;
//                      when copyIntoFrameBuffer() returns,
//                      readPtr points just past the end of the
//                      copied data.
//
//    writePtr, endPtr  point to the lefmost and rightmost pixels
//                      in the frame buffer slice
//
//    xStride           the xStride for the frame buffer slice
//
//    format            indicates if the line or tile buffer is
//                      in NATIVE or XDR format.
//
//    typeInFrameBuffer the pixel data type of the frame buffer slice
//
//    typeInFile        the pixel data type in the input file's channel
//

IMF_EXPORT
void copyIntoFrameBuffer (
    const char*&       readPtr,
    char*              writePtr,
    char*              endPtr,
    size_t             xStride,
    bool               fill,
    double             fillValue,
    Compressor::Format format,
    PixelType          typeInFrameBuffer,
    PixelType          typeInFile);

//
// Copy a single channel of a horizontal row of pixels from an
// input file's internal line buffer or tile buffer into a
// frame buffer slice.  If necessary, perform on-the-fly data
// type conversion.
//
//    readPtr             initially points to the beginning of the
//                        data in the line or tile buffer. readPtr
//                        is advanced as the pixel data are copied;
//                        when copyIntoFrameBuffer() returns,
//                        readPtr points just past the end of the
//                        copied data.
//
//    base                point to each pixel in the framebuffer
//
//    sampleCountBase,    provide the number of samples in each pixel
//    sampleCountXStride,
//    sampleCountYStride
//
//    y                   the scanline to copy. The coordinate is
//                        relative to the datawindow.min.y.
//
//    minX, maxX          used to indicate which pixels in the scanline
//                        will be copied.
//
//    xOffsetForSampleCount,    used to offset the sample count array
//    yOffsetForSampleCount,    and the base array.
//    xOffsetForData,
//    yOffsetForData
//
//    xStride             the xStride for the frame buffer slice
//
//    format              indicates if the line or tile buffer is
//                        in NATIVE or XDR format.
//
//    typeInFrameBuffer   the pixel data type of the frame buffer slice
//
//    typeInFile          the pixel data type in the input file's channel
//

IMF_EXPORT
void copyIntoDeepFrameBuffer (
    const char*&       readPtr,
    char*              base,
    const char*        sampleCountBase,
    ptrdiff_t          sampleCountXStride,
    ptrdiff_t          sampleCountYStride,
    int                y,
    int                minX,
    int                maxX,
    int                xOffsetForSampleCount,
    int                yOffsetForSampleCount,
    int                xOffsetForData,
    int                yOffsetForData,
    ptrdiff_t          xStride,
    ptrdiff_t          xPointerStride,
    ptrdiff_t          yPointerStride,
    bool               fill,
    double             fillValue,
    Compressor::Format format,
    PixelType          typeInFrameBuffer,
    PixelType          typeInFile);

//
// Given a pointer into a an input file's line buffer or tile buffer,
// skip over the data for xSize pixels of type typeInFile.
// readPtr initially points to the beginning of the data to be skipped;
// when skipChannel() returns, readPtr points just past the end of the
// skipped data.
//

IMF_EXPORT
void skipChannel (const char*& readPtr, PixelType typeInFile, size_t xSize);

//
// Convert an array of pixel data from the machine's native
// representation to XDR format.
//
//    toPtr, fromPtr    initially point to the beginning of the input
//                      and output pixel data arrays; when convertInPlace()
//                      returns, toPtr and fromPtr point just past the
//                      end of the input and output arrays.
//                      If the native representation of the data has the
//                      same size as the XDR data, then the conversion
//                      can take in place, without an intermediate
//                      temporary buffer (toPtr and fromPtr can point
//                      to the same location).
//
//    type              the pixel data type
//
//    numPixels         number of pixels in the input and output arrays
//

IMF_EXPORT
void convertInPlace (
    char*& toPtr, const char*& fromPtr, PixelType type, size_t numPixels);

//
// Copy a single channel of a horizontal row of pixels from a
// a frame buffer into an output file's internal line buffer or
// tile buffer.
//
//    writePtr          initially points to the beginning of the
//                      data in the line or tile buffer. writePtr
//                      is advanced as the pixel data are copied;
//                      when copyFromFrameBuffer() returns,
//                      writePtr points just past the end of the
//                      copied data.
//
//    readPtr, endPtr   point to the lefmost and rightmost pixels
//                      in the frame buffer slice
//
//    xStride           the xStride for the frame buffer slice
//
//    format            indicates if the line or tile buffer is
//                      in NATIVE or XDR format.
//
//    type              the pixel data type in the frame buffer
//                      and in the output file's channel (function
//                      copyFromFrameBuffer() doesn't do on-the-fly
//                      data type conversion)
//

IMF_EXPORT
void copyFromFrameBuffer (
    char*&             writePtr,
    const char*&       readPtr,
    const char*        endPtr,
    size_t             xStride,
    Compressor::Format format,
    PixelType          type);

//
// Copy a single channel of a horizontal row of pixels from a
// a frame buffer in a deep data file into an output file's
// internal line buffer or tile buffer.
//
//    writePtr                  initially points to the beginning of the
//                              data in the line or tile buffer. writePtr
//                              is advanced as the pixel data are copied;
//                              when copyFromDeepFrameBuffer() returns,
//                              writePtr points just past the end of the
//                              copied data.
//
//    base                      the start pointer of each pixel in this channel.
//                              It points to the real data in FrameBuffer.
//                              It is different for different channels.
//                              dataWindowMinX and dataWindowMinY are involved in
//                              locating for base.
//
//    sampleCountBase,          used to locate the position to get
//    sampleCountXStride,       the number of samples for each pixel.
//    sampleCountYStride        Used to determine how far we should
//                              read based on the pointer provided by base.
//
//    y                         the scanline to copy. If we are dealing
//                              with a tiled deep file, then probably a portion
//                              of the scanline is copied.
//
//    xMin, xMax                used to indicate which pixels in the scanline
//                              will be copied.
//
//    xOffsetForSampleCount,    used to offset the sample count array
//    yOffsetForSampleCount,    and the base array.
//    xOffsetForData,
//    yOffsetForData
//
//    xStride                   the xStride for the frame buffer slice
//
//    format                    indicates if the line or tile buffer is
//                              in NATIVE or XDR format.
//
//    type                      the pixel data type in the frame buffer
//                              and in the output file's channel (function
//                              copyFromFrameBuffer() doesn't do on-the-fly
//                              data type conversion)
//

IMF_EXPORT
void copyFromDeepFrameBuffer (
    char*&             writePtr,
    const char*        base,
    char*              sampleCountBase,
    ptrdiff_t          sampleCountXStride,
    ptrdiff_t          sampleCountYStride,
    int                y,
    int                xMin,
    int                xMax,
    int                xOffsetForSampleCount,
    int                yOffsetForSampleCount,
    int                xOffsetForData,
    int                yOffsetForData,
    ptrdiff_t          sampleStride,
    ptrdiff_t          xStrideForData,
    ptrdiff_t          yStrideForData,
    Compressor::Format format,
    PixelType          type);

//
// Fill part of an output file's line buffer or tile buffer with
// zeroes.  This routine is called when an output file contains
// a channel for which the frame buffer contains no corresponding
// slice.
//
//    writePtr          initially points to the beginning of the
//                      data in the line or tile buffer.  When
//                      fillChannelWithZeroes() returns, writePtr
//                      points just past the end of the zeroed
//                      data.
//
//    format            indicates if the line or tile buffer is
//                      in NATIVE or XDR format.
//
//    type              the pixel data type in the line or frame buffer.
//
//    xSize             number of pixels to be filled with zeroes.
//

IMF_EXPORT
void fillChannelWithZeroes (
    char*& writePtr, Compressor::Format format, PixelType type, size_t xSize);

IMF_EXPORT
bool usesLongNames (const Header& header);

//
// compute size of chunk offset table - for existing types, computes
// the chunk size from the image size, compression type, and tile
// description (for tiled types). If the type is not supported, uses
// the chunkCount attribute if present, or throws an exception
// otherwise
//

IMF_EXPORT
int getChunkOffsetTableSize (const Header& header);

//
// Convert a filename to a wide string.  This is useful for working with
// filenames on Windows.
//

IMF_EXPORT
std::wstring WidenFilename (const char* filename);

//
// Return the string that describes the major.minor.patch release version
//

IMF_EXPORT const char* getLibraryVersion();

OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT

#endif