image_io.h

来自「JPEG2000实现的源码」· C头文件 代码 · 共 199 行

/*****************************************************************************/
/* Copyright 1998, Hewlett-Packard Company                                   */
/* All rights reserved                                                       */
/* File: "image_io.h"                                                        */
/* Description: standard interface definitions for image reading and writing */
/*              objects.                                                     */
/* Author: David Taubman                                                     */
/* Affiliation: Hewlett-Packard and                                          */
/*              The University of New South Wales, Australia                 */
/* Version: VM9.0                                                            */
/* Last Revised: 18 April, 2001                                              */
/*****************************************************************************/
#ifndef IMAGE_IO_H
#define IMAGE_IO_H
#include <ifc.h>

#define IMAGE_IO_MEM_KEY "IMAGE I/O OBJECT MEMORY"

/* ========================================================================= */
/* -------------------------- Forward Definitions -------------------------- */
/* ========================================================================= */

typedef struct image_reader_obj *image_reader_ref;
typedef struct image_writer_obj *image_writer_ref;

/* ========================================================================= */
/* ------------------------- Interface Definitions ------------------------- */
/* ========================================================================= */

/*****************************************************************************/
/*                               image_reader                                */
/*****************************************************************************/

typedef void (*image_reader__initialize__func)
  (image_reader_ref self, int *num_components, cmdl_ref cmdl);
    /* Initializes the `image_reader' object.  The function parses command
       line arguments to locate the relevant file names and file format
       characteristics.
           `num_components' is used to return the number of image components
       available from the input file(s).  Image components are often
       associated with colour planes, but this is not necessary.  In fact,
       each component may have a different dimension, but this information
       must be recovered later by calling the `image_reader__get_dims'
       function. 
           `cmdl' is provided so that the initialization function
       can look for additional special switches which customize its behaviour.
       Special switches should, as a matter of convention, have the prefix,
       "-i".  Moreover, the policy described in "ifc.h" under the section
       entitled "Modular Command Line Argument Management" should be strictly
       followed. */

typedef char ** (*image_reader__get_usage__func)
  (image_reader_ref self);
    /* For a description of the role played by the `get_usage' function,
       consult the comments appearing in "ifc.h" under the section entitled
       "Modular Command Line Argument Management". */

typedef void (*image_reader__get_dims__func)
  (image_reader_ref self, int component_idx, canvas_dims_ptr dims);
    /* This function returns the width and height of the relevant component
       via the structure referenced by the `dims' pointer. */

typedef int (*image_reader__get_dynamic_range__func)
  (image_reader_ref self, int component_idx);
    /* This function returns information about the dynamic range of the
       indicated image component.  If the return value is negative then the
       image sample values lie within the signed, symmetric range of
       -2^{R-1} to 2^{R-1}-1, where R is the absolute value of the return
       value.  If the return value is non-negative then the image sample
       values lie within the unsigned range of 0 to 2^{R}-1, where R is
       the return value. */

typedef void (*image_reader__pull_line__func)
  (image_reader_ref self, ifc_int *line_buf, int component_idx, int width);
    /* This function is used to recover the next image line from the
       indicated component.  The `width' argument is supplied only for
       consistency checking -- it must be identical to the width of the
       relevant component, as returned by `image_reader__get_dims'.  The
       `line_buf' argument points to an array with at least `width' entries,
       into which the sample values will be written. */

typedef void (*image_reader__terminate__func)
  (image_reader_ref self);
    /* This function will be called once all required image data has been
       read.  It should deallocate any memory which was allocated,
       including the memory allocated for the structure pointed to by
       `self'. */

typedef
  struct image_reader_obj {
    image_reader__initialize__func initialize;
    image_reader__get_usage__func get_usage;
    image_reader__get_dims__func get_dims;
    image_reader__get_dynamic_range__func get_dynamic_range;
    image_reader__pull_line__func pull_line;
    image_reader__terminate__func terminate;
  } image_reader_obj;
  /* This structure defines all externally visible aspects of the
     `image_reader' object.  In practice, when the object is created, the
     relevant implementation will create a larger structure, containing
     this structure as its first entry and including all relevant fields
     required to maintain state information.  As mentioned in the
     introductory comments of "ifc.h", the external view of any given
     object consists only in a set of function pointers which define the
     interface to be used by all relevant parties.   The function pointers
     must be set to the addresses of the relevant functions when the
     object is created (i.e. when the structure is allocated and assigned
     an initial state).
         The image reader provides a service for reading from the input image
     file(s) one line at a time.  It relieves its clients of the burden of
     dealing with particular file formats.
         The object is defined here, rather than with the other objects
     in "ifc.h", because it is not strictly part of the compression system. */

/*****************************************************************************/
/*                               image_writer                                */
/*****************************************************************************/

typedef void (*image_writer__initialize__func)
  (image_writer_ref self, int num_components, int dynamic_ranges[],
   canvas_dims_ptr dims, 
   /* Begin Aerospace MCT mods (TSW) */
   int *dims_reference,
   /* End Aeropsace MCT mods */
   cmdl_ref cmdl);
    /* Initializes the `image_writer' object.  The function parses command
       line arguments to locate the relevant file names and file format
       characteristics.
           `num_components' indicates the number of image components which
       are available.
           `dynamic_ranges' must point to an array with one entry for each
       component, indicating whether or not the sample values are signed and
       how many bits are required to span their dynamic range.  The
       interpretation of these values is identical to the interpretation of
       the values returned by `image_reader__get_dynamic_range'.
           `dims' must point to an array with one entry for each component.
       It is used to return the dimensions of each component.
  Begin Aerospace MCT mods (TSW)
           'dims_reference' is a pointer to an array of indices that are
       used to determine the correct size information for an output image
       in the possible presence of a multi-component linear transform.
  End Aerospace MCT mods
           `cmdl' is provided so that the initialization function
       can look for additional special switches which customize its behaviour.
       Special switches should, as a matter of convention, have the prefix,
       "-o".  The policy described in "ifc.h" under the section entitled
       "Modular Command Line Argument Management" should be strictly
       followed. */

typedef char ** (*image_writer__get_usage__func)
  (image_writer_ref self);
    /* For a description of the role played by the `get_usage' function,
       consult the comments appearing in "ifc.h" under the section entitled
       "Modular Command Line Argument Management". */

typedef void (*image_writer__push_line__func)
  (image_writer_ref self, ifc_int *line_buf, int component_idx, int width);
    /* This function is used to save the next image line for the
       indicated component.  The `width' argument is supplied only for
       consistency checking -- it must be identical to the width of the
       relevant component, as supplied to to `image_writer__initialize'.
       The `line_buf' argument points to an array with at least `width'
       entries, from which the sample values will be taken.  The function
       clips any values which exceed the dynamic range supplied to
       `image_writer__initialize'. */

typedef void (*image_writer__terminate__func)
  (image_writer_ref self);
    /* This function will be called once all required image data has been
       read.  It should deallocate any memory which was allocated,
       including the memory allocated for the structure pointed to by
       `self'. */

typedef
  struct image_writer_obj {
    image_writer__initialize__func initialize;
    image_writer__get_usage__func get_usage;
    image_writer__push_line__func push_line;
    image_writer__terminate__func terminate;
  } image_writer_obj;
  /* This structure defines all externally visible aspects of the
     `image_writer' object.  In practice, when the object is created, the
     relevant implementation will create a larger structure, containing
     this structure as its first entry and including all relevant fields
     required to maintain state information.  As mentioned in the
     introductory comments of "ifc.h", the external view of any given
     object consists only in a set of function pointers which define the
     interface to be used by all relevant parties.   The function pointers
     must be set to the addresses of the relevant functions when the
     object is created (i.e. when the structure is allocated and assigned
     an initial state).
         The image writer provides a service for writing the output image
     file(s) one line at a time.  It relieves its clients of the burden of
     dealing with particular file formats.
         The object is defined here, rather than with the other objects
     in "ifc.h", because it is not strictly part of the compression system. */

#endif /* IMAGE_IO_H */