Panda3D
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes

PNMReader Class Reference

This is an abstract base class that defines the interface for reading image files of various types. More...

#include "pnmReader.h"

Inheritance diagram for PNMReader:
PNMImageHeader

List of all members.

Public Types

enum  ColorType {
  CT_invalid = 0, CT_grayscale = 1, CT_two_channel = 2, CT_color = 3,
  CT_four_channel = 4
}
typedef pmap< PixelSpec, int > HistMap
typedef pvector< PixelSpecPalette
typedef pvector< PixelSpecCountPixelCount

Public Member Functions

ColorType get_color_type () const
 Returns the image type of the image, as an enumerated value.
string get_comment () const
 Gets the user comment from the file.
xelval get_maxval () const
 Returns the maximum channel value allowable for any pixel in this image; for instance, 255 for a typical 8-bit-per-channel image.
int get_num_channels () const
 Returns the number of channels in the image.
PNMFileTypeget_type () const
 Returns a pointer to the PNMFileType object that created this PNMReader.
int get_x_size () const
 Returns the number of pixels in the X direction.
int get_y_size () const
 Returns the number of pixels in the Y direction.
bool has_alpha () const
 Returns true if the image includes an alpha channel, false otherwise.
bool has_type () const
 Returns true if the PNMImageHeader knows what type it is, false otherwise.
bool is_grayscale () const
 Returns false if the image is a full-color image, and has red, green, and blue components; true if it is a grayscale image and has only a gray component.
bool is_valid () const
 Returns true if the PNMReader can be used to read data, false if something is wrong.
PNMReadermake_reader (const Filename &filename, PNMFileType *type=NULL, bool report_unknown_type=true) const
 Returns a newly-allocated PNMReader of the suitable type for reading from the indicated image filename, or NULL if the filename cannot be read for some reason.
PNMReadermake_reader (istream *file, bool owns_file=true, const Filename &filename=Filename(), string magic_number=string(), PNMFileType *type=NULL, bool report_unknown_type=true) const
 Returns a newly-allocated PNMReader of the suitable type for reading from the already-opened image file, or NULL if the file cannot be read for some reason.
PNMWritermake_writer (const Filename &filename, PNMFileType *type=NULL) const
 Returns a newly-allocated PNMWriter of the suitable type for writing an image to the indicated filename, or NULL if the filename cannot be written for some reason.
PNMWritermake_writer (ostream *file, bool owns_file=true, const Filename &filename=Filename(), PNMFileType *type=NULL) const
 Returns a newly-allocated PNMWriter of the suitable type for writing to the already-opened image file, or NULL if the file cannot be written for some reason.
void output (ostream &out) const
virtual void prepare_read ()
 This method will be called before read_data() or read_row() is called.
virtual int read_data (xel *array, xelval *alpha)
 Reads in an entire image all at once, storing it in the pre-allocated _x_size * _y_size array and alpha pointers.
bool read_header (const Filename &filename, PNMFileType *type=NULL, bool report_unknown_type=true)
 Opens up the image file and tries to read its header information to determine its size, number of channels, etc.
bool read_header (istream &data, const string &filename=string(), PNMFileType *type=NULL, bool report_unknown_type=true)
 Reads the image header information only from the indicated stream.
virtual bool read_row (xel *array, xelval *alpha, int x_size, int y_size)
 If supports_read_row(), above, returns true, this function may be called repeatedly to read the image, one horizontal row at a time, beginning from the top.
void set_comment (const string &comment)
 Writes a user comment string to the image (header).
void set_read_size (int x_size, int y_size)
 Instructs the reader to attempt to scale the image to the indicated size while reading it.
void set_type (PNMFileType *type)
 Sets the file type of this PNMImage.
virtual bool supports_read_row () const
 Returns true if this particular PNMReader is capable of returning the data one row at a time, via repeated calls to read_row().
virtual bool supports_stream_read () const
 Returns true if this particular PNMReader can read from a general stream (including pipes, etc.), or false if the reader must occasionally fseek() on its input stream, and thus only disk streams are supported.

Static Public Member Functions

static bool has_alpha (ColorType color_type)
 This static variant of has_alpha() returns true if the indicated image type includes an alpha channel, false otherwise.
static bool is_grayscale (ColorType color_type)
 This static variant of is_grayscale() returns true if the indicated image type represents a grayscale image, false otherwise.
static bool read_magic_number (istream *file, string &magic_number, int num_bytes)
 Ensures that the first n bytes of the file are read into magic_number.

Protected Member Functions

 PNMReader (PNMFileType *type, istream *file, bool owns_file)
bool compute_histogram (HistMap &hist, xel *array, xelval *alpha, int max_colors=0)
 Computes a histogram of the colors used in the indicated rgb/grayscale array and/or alpha array.
bool compute_palette (Palette &palette, xel *array, xelval *alpha, int max_colors=0)
 Returns a linear list of all of the colors in the image, similar to compute_histogram().
void record_color (HistMap &hist, const PixelSpec &color)
 Records the indicated color in the histogram.

Protected Attributes

string _comment
istream * _file
bool _has_read_size
bool _is_valid
xelval _maxval
int _num_channels
int _orig_x_size
int _orig_y_size
bool _owns_file
int _read_x_size
int _read_y_size
PNMFileType_type
int _x_shift
int _x_size
int _y_shift
int _y_size

Detailed Description

This is an abstract base class that defines the interface for reading image files of various types.

Any particular image file type that can be read must define a class that inherits from PNMReader to read it.

Definition at line 31 of file pnmReader.h.


Member Function Documentation

bool PNMImageHeader::compute_histogram ( PNMImageHeader::HistMap &  hist,
xel array,
xelval *  alpha,
int  max_colors = 0 
) [protected, inherited]

Computes a histogram of the colors used in the indicated rgb/grayscale array and/or alpha array.

This is most likely to be useful in a PNMWriter class, but it is defined at this level in case it has general utilty for PNMImages.

Also see PNMImage::make_histogram(), which is a higher-level function.

The max_colors parameter, if greater than zero, limits the maximum number of colors we are interested in. If we encounter more than this number of colors, the function aborts before completion and returns false; otherwise, it returns true.

Definition at line 450 of file pnmImageHeader.cxx.

References PNMImageHeader::get_color_type(), and PNMImageHeader::record_color().

Referenced by PNMImageHeader::compute_palette(), and PNMImage::make_histogram().

bool PNMImageHeader::compute_palette ( PNMImageHeader::Palette &  palette,
xel array,
xelval *  alpha,
int  max_colors = 0 
) [protected, inherited]

Returns a linear list of all of the colors in the image, similar to compute_histogram().

Definition at line 506 of file pnmImageHeader.cxx.

References PNMImageHeader::compute_histogram().

PNMImageHeader::ColorType PNMImageHeader::get_color_type ( ) const [inline, inherited]

Returns the image type of the image, as an enumerated value.

This is really just the number of channels cast to the enumerated type.

Definition at line 76 of file pnmImageHeader.I.

Referenced by PNMImageHeader::compute_histogram(), osxGraphicsPipe::create_cg_image(), PNMImageHeader::has_alpha(), PNMImageHeader::is_grayscale(), and PNMImage::set_color_type().

string PNMImageHeader::get_comment ( ) const [inline, inherited]

Gets the user comment from the file.

Definition at line 186 of file pnmImageHeader.I.

xelval PNMImageHeader::get_maxval ( ) const [inline, inherited]
int PNMImageHeader::get_num_channels ( ) const [inline, inherited]
PNMFileType * PNMReader::get_type ( ) const [inline]

Returns a pointer to the PNMFileType object that created this PNMReader.

Reimplemented from PNMImageHeader.

Definition at line 54 of file pnmReader.I.

int PNMImageHeader::get_x_size ( ) const [inline, inherited]
int PNMImageHeader::get_y_size ( ) const [inline, inherited]
bool PNMImageHeader::has_alpha ( PNMImageHeader::ColorType  color_type) [inline, static, inherited]
bool PNMImageHeader::has_alpha ( ) const [inline, inherited]
bool PNMImageHeader::has_type ( ) const [inline, inherited]

Returns true if the PNMImageHeader knows what type it is, false otherwise.

Definition at line 207 of file pnmImageHeader.I.

bool PNMImageHeader::is_grayscale ( PNMImageHeader::ColorType  color_type) [inline, static, inherited]

This static variant of is_grayscale() returns true if the indicated image type represents a grayscale image, false otherwise.

Definition at line 100 of file pnmImageHeader.I.

bool PNMImageHeader::is_grayscale ( ) const [inline, inherited]

Returns false if the image is a full-color image, and has red, green, and blue components; true if it is a grayscale image and has only a gray component.

(The gray color is actually stored in the blue channel, and the red and green channels are ignored.)

Definition at line 114 of file pnmImageHeader.I.

References PNMImageHeader::get_color_type().

Referenced by PNMImage::add_alpha(), PNMImage::make_grayscale(), PNMImage::remove_alpha(), PNMImage::set_color_type(), and PNMImage::set_maxval().

bool PNMReader::is_valid ( ) const [inline]

Returns true if the PNMReader can be used to read data, false if something is wrong.

Definition at line 65 of file pnmReader.I.

Referenced by PNMImageHeader::make_reader(), PNMImage::read(), and read_data().

PNMReader * PNMImageHeader::make_reader ( istream *  file,
bool  owns_file = true,
const Filename filename = Filename(),
string  magic_number = string(),
PNMFileType type = NULL,
bool  report_unknown_type = true 
) const [inherited]

Returns a newly-allocated PNMReader of the suitable type for reading from the already-opened image file, or NULL if the file cannot be read for some reason.

owns_file should be set true if the PNMReader is to be considered the owner of the stream pointer (in which case the stream will be deleted on completion, whether successful or not), or false if it should not delete it.

The filename parameter is optional here, since the file has already been opened; it is only used to examine the extension and attempt to guess the file type.

If magic_number is nonempty, it is assumed to represent the first few bytes that have already been read from the file. Some file types may have difficulty if this is more than two bytes.

If type is non-NULL, it is a suggestion for the file type to use.

The PNMReader should be deleted when it is no longer needed.

Definition at line 155 of file pnmImageHeader.cxx.

References VirtualFileSystem::close_read_file(), PNMFileTypeRegistry::get_global_ptr(), VirtualFileSystem::get_global_ptr(), PNMFileTypeRegistry::get_type_from_extension(), is_valid(), PNMFileType::make_reader(), and PNMImageHeader::read_magic_number().

PNMReader * PNMImageHeader::make_reader ( const Filename filename,
PNMFileType type = NULL,
bool  report_unknown_type = true 
) const [inherited]

Returns a newly-allocated PNMReader of the suitable type for reading from the indicated image filename, or NULL if the filename cannot be read for some reason.

The filename "-" always stands for standard input. If type is specified, it is a suggestion for the file type to use.

The PNMReader should be deleted when it is no longer needed.

Definition at line 89 of file pnmImageHeader.cxx.

References VirtualFileSystem::get_global_ptr(), and VirtualFileSystem::open_read_file().

Referenced by PNMImage::read(), and PNMImageHeader::read_header().

PNMWriter * PNMImageHeader::make_writer ( ostream *  file,
bool  owns_file = true,
const Filename filename = Filename(),
PNMFileType type = NULL 
) const [inherited]

Returns a newly-allocated PNMWriter of the suitable type for writing to the already-opened image file, or NULL if the file cannot be written for some reason.

owns_file should be set true if the PNMWriter is to be considered the owner of the stream pointer (in which case the stream will be deleted on completion, whether successful or not), or false if it should not delete it.

The filename parameter is optional here, since the file has already been opened; it is only used to examine the extension and attempt to guess the intended file type.

If type is non-NULL, it is a suggestion for the file type to use.

The PNMWriter should be deleted when it is no longer needed.

Definition at line 343 of file pnmImageHeader.cxx.

References PNMFileTypeRegistry::get_global_ptr(), PNMFileTypeRegistry::get_type_from_extension(), PNMWriter::is_valid(), and PNMFileType::make_writer().

PNMWriter * PNMImageHeader::make_writer ( const Filename filename,
PNMFileType type = NULL 
) const [inherited]

Returns a newly-allocated PNMWriter of the suitable type for writing an image to the indicated filename, or NULL if the filename cannot be written for some reason.

The filename "-" always stands for standard output. If type is specified, it is a suggestion for the file type to use.

The PNMWriter should be deleted when it is no longer needed.

Definition at line 270 of file pnmImageHeader.cxx.

References Filename::get_extension(), and Filename::open_write().

Referenced by PNMImage::write().

void PNMReader::prepare_read ( ) [virtual]

This method will be called before read_data() or read_row() is called.

It instructs the reader to initialize its data structures as necessary to actually perform the read operation.

After this call, _x_size and _y_size should reflect the actual size that will be filled by read_data() (as possibly modified by set_read_size()).

Definition at line 52 of file pnmReader.cxx.

References supports_read_row().

Referenced by PNMImage::read().

int PNMReader::read_data ( xel array,
xelval *  alpha 
) [virtual]

Reads in an entire image all at once, storing it in the pre-allocated _x_size * _y_size array and alpha pointers.

(If the image type has no alpha channel, alpha is ignored.) Returns the number of rows correctly read.

Derived classes need not override this if they instead provide supports_read_row() and read_row(), below.

Definition at line 87 of file pnmReader.cxx.

References Thread::consider_yield(), PNMImageHeader::has_alpha(), is_valid(), and read_row().

Referenced by PNMImage::read().

bool PNMImageHeader::read_header ( const Filename filename,
PNMFileType type = NULL,
bool  report_unknown_type = true 
) [inherited]

Opens up the image file and tries to read its header information to determine its size, number of channels, etc.

If successful, updates the header information and returns true; otherwise, returns false.

Definition at line 34 of file pnmImageHeader.cxx.

References PNMImageHeader::make_reader().

Referenced by Texture::do_read_one(), SourceTextureImage::read_header(), and GeoMipTerrain::set_heightfield().

bool PNMImageHeader::read_header ( istream &  data,
const string &  filename = string(),
PNMFileType type = NULL,
bool  report_unknown_type = true 
) [inherited]

Reads the image header information only from the indicated stream.

The filename is advisory only, and may be used to suggest a type if it has a known extension.

If type is non-NULL, it is a suggestion for the type of file it is (and a non-NULL type will override any magic number test or filename extension lookup).

Returns true if successful, false on error.

Definition at line 62 of file pnmImageHeader.cxx.

References PNMImageHeader::make_reader().

bool PNMImageHeader::read_magic_number ( istream *  file,
string &  magic_number,
int  num_bytes 
) [static, inherited]

Ensures that the first n bytes of the file are read into magic_number.

If magic_number is initially nonempty, assumes these represent the first few bytes already extracted. Returns true if successful, false if an end of file or error occurred before num_bytes could be read.

Definition at line 408 of file pnmImageHeader.cxx.

Referenced by PNMImageHeader::make_reader().

bool PNMReader::read_row ( xel array,
xelval *  alpha,
int  x_size,
int  y_size 
) [virtual]

If supports_read_row(), above, returns true, this function may be called repeatedly to read the image, one horizontal row at a time, beginning from the top.

Returns true if the row is successfully read, false if there is an error or end of file.

The x_size and y_size parameters are the value of _x_size and _y_size as originally filled in by the constructor; it is the actual number of pixels in the image. (The _x_size and _y_size members may have been automatically modified by the time this method is called if we are scaling on load, so should not be used.)

Definition at line 227 of file pnmReader.cxx.

Referenced by read_data().

void PNMImageHeader::record_color ( PNMImageHeader::HistMap &  hist,
const PixelSpec color 
) [inline, protected, inherited]

Records the indicated color in the histogram.

Definition at line 244 of file pnmImageHeader.I.

Referenced by PNMImageHeader::compute_histogram().

void PNMImageHeader::set_comment ( const string &  comment) [inline, inherited]

Writes a user comment string to the image (header).

Definition at line 196 of file pnmImageHeader.I.

Referenced by DisplayRegion::save_screenshot().

void PNMReader::set_read_size ( int  x_size,
int  y_size 
) [inline]

Instructs the reader to attempt to scale the image to the indicated size while reading it.

The reader may or may not follow this suggestion, or may follow it only partially (e.g. by reading a file which is slightly reduced in size, but not the precise size requested).

Definition at line 41 of file pnmReader.I.

Referenced by PNMImage::read().

void PNMImageHeader::set_type ( PNMFileType type) [inline, inherited]

Sets the file type of this PNMImage.

This will be the default type used when an image is read, if the type cannot be determined by magic number or inferred by extension, or the type used when the image is written, if the type cannot be inferred from the filename extension.

Definition at line 234 of file pnmImageHeader.I.

Referenced by ImageFile::read().

bool PNMReader::supports_read_row ( ) const [virtual]

Returns true if this particular PNMReader is capable of returning the data one row at a time, via repeated calls to read_row().

Returns false if the only way to read from this file is all at once, via read_data().

Definition at line 205 of file pnmReader.cxx.

Referenced by prepare_read().

bool PNMReader::supports_stream_read ( ) const [virtual]

Returns true if this particular PNMReader can read from a general stream (including pipes, etc.), or false if the reader must occasionally fseek() on its input stream, and thus only disk streams are supported.

Definition at line 242 of file pnmReader.cxx.


The documentation for this class was generated from the following files:
 All Classes Functions Variables Enumerations