png::consumer< pixel, pixcon, info_holder, interlacing_supported > Class Template Reference

Pixel consumer class template. More...

`#include <consumer.hpp>`

Inheritance diagram for png::consumer< pixel, pixcon, info_holder, interlacing_supported >:

## Classes

struct | transform_identity
| The default io transformation: does nothing. More...

## Public Types

typedef pixel_traits< pixel > | traits
Public Types inherited from png::streaming_base< pixel, info_holder >
typedef pixel_traits< pixel > | traits

## Public Member Functions

template<typename istream >
void | read (istream &stream)
| Reads an image from the stream using default io transformation.
template<typename istream , class transformation >
void | read (istream &stream, transformation const &transform)
| Reads an image from the stream using custom io transformation.
Public Member Functions inherited from png::streaming_base< pixel, info_holder >
| streaming_base (image_info &info)
| streaming_base (uint_32 width, uint_32 height)
image_info const & | get_info () const

## Protected Types

typedef streaming_base< pixel, info_holder > | base

## Protected Member Functions

| consumer (image_info &info)
| Constructs a consumer object using passed image_info object to store image information.
Protected Member Functions inherited from png::streaming_base< pixel, info_holder >
void | reset (size_t)
image_info & | get_info ()

## Additional Inherited Members

Protected Attributes inherited from png::streaming_base< pixel, info_holder >
info_holder | m_info_holder

## Detailed Description

template<typename pixel, class pixcon, class info_holder = def_image_info_holder, bool interlacing_supported = false>
class png::consumer< pixel, pixcon, info_holder, interlacing_supported >

Pixel consumer class template.

Used as a base class for custom pixel consumer classes as well as inside image class implementation to read pixels into the pixel buffer.

Encapsulates PNG image reading procedure. In order to create a custom pixel consumer use CRTP trick:

class pixel_consumer
: public png::consumer< pixel, pixel_consumer >
{
...
};
png::consumer
Pixel consumer class template.
Definition consumer.hpp:127

Your pixel consumer class should implement `get_next_row()` method and `reset()` method (optional). Their signatures are as follows:

png::byte* get_next_row(png::uint_32 pos);
void reset(size_t pass);
png::reader
The PNG reader class template. This is the low-level reading interface–use image class or consumer cl...
Definition reader.hpp:67
png::streaming_base::reset
void reset(size_t)
Definition streaming_base.hpp:113

The `get_next_row()` method is called every time a new row of image data is available to the reader. The position of the row being read is passed as `pos` parameter. The `pos` takes values from `0` to `` <image_height>-1 inclusively. The method should return the starting address of a row buffer capable of storing appropriate amount of pixels (i.e. the width of the image being read). The address should be casted to png::byte* pointer type using `reinterpret_cast<>` or a C-style cast.

The optional `reset()` method is called every time the new pass of interlaced image processing starts. The number of interlace pass is avaiable as the only parameter of the method. For non-interlaced images the method is called once prior to any calls to `get_next_row()`. The value of `0` is passed for the `pass` number.

An optional template parameter `info_holder` encapsulates image_info storage policy. Using def_image_info_holder results in image_info object stored as a sub-object of the consumer class. You may specify image_info_ref_holder in order to use a reference to the externally stored image_info object. This way you will have to construct the consumer object passing the reference to image_info object.

Also, you might want implement an info holder object yourself to fine-tune your code. In any case, you can access the image_info object from your consumer class methods using the following code:

png::image_info& info = m_info_holder.get_info();
png::image_info
Holds information about PNG image.
Definition image_info.hpp:48
png::info
Holds information about PNG image. Adapter class for IO image operations.
Definition info.hpp:48
png::io_base::get_info
info & get_info()
Definition io_base.hpp:87
png::streaming_base::m_info_holder
info_holder m_info_holder
Definition streaming_base.hpp:123

An optional `bool` template parameter `interlacing_supported` specifies whether reading interlacing images is supported by your consumer class. It defaults to `false`. An attempt to read an interlaced image will result in discarding pixels obtained at all the interlacing passes except the last one.

In order to fully support interlacing specify `true` for `interlacing_supported` parameter and implement `reset()` method.

See also
  image, generator

## Member Typedef Documentation

## traits

template<typename pixel , class pixcon , class info_holder = def_image_info_holder, bool interlacing_supported = false>

typedef pixel_traits< pixel > png::consumer< pixel, pixcon, info_holder, interlacing_supported >::traits

## base

template<typename pixel , class pixcon , class info_holder = def_image_info_holder, bool interlacing_supported = false>

typedef streaming_base< pixel, info_holder > png::consumer< pixel, pixcon, info_holder, interlacing_supported >::base

protected

## Constructor & Destructor Documentation

## consumer()

template<typename pixel , class pixcon , class info_holder = def_image_info_holder, bool interlacing_supported = false>

png::consumer< pixel, pixcon, info_holder, interlacing_supported >::consumer | ( | image_info & | info | ) |

inline explicit protected

Constructs a consumer object using passed image_info object to store image information.

## Member Function Documentation

## read() [1/2]

template<typename pixel , class pixcon , class info_holder = def_image_info_holder, bool interlacing_supported = false>
template<typename istream >

void png::consumer< pixel, pixcon, info_holder, interlacing_supported >::read | ( | istream & | stream | ) |

inline

Reads an image from the stream using default io transformation.

References png::consumer< pixel, pixcon, info_holder, interlacing_supported >::read().

Referenced by png::consumer< pixel, pixcon, info_holder, interlacing_supported >::read().

## read() [2/2]

template<typename pixel , class pixcon , class info_holder = def_image_info_holder, bool interlacing_supported = false>
template<typename istream , class transformation >

void png::consumer< pixel, pixcon, info_holder, interlacing_supported >::read | ( | istream & | stream,
|  | transformation const & | transform
| ) |  |

inline

Reads an image from the stream using custom io transformation.

Essentially, this method constructs a reader object and instructs it to read the image from the stream. It handles IO transformation, as well as interlaced image reading.

References png::io_base::get_bit_depth(), png::io_base::get_color_type(), png::io_base::get_image_info(), png::streaming_base< pixel, info_holder >::get_info(), png::io_base::get_interlace_type(), png::interlace_none, png::reader< istream >::read_end_info(), png::reader< istream >::read_info(), png::io_base::set_interlace_handling(), png::io_base::set_swap(), and png::reader< istream >::update_info().

The documentation for this class was generated from the following file:

- consumer.hpp