Struct png::Writer

pub struct Writer<W: Write> {
    w: W,
    info: PartialInfo,
    options: Options,
    images_written: u64,
    animation_written: u32,
    iend_written: bool,
}

PNG writer

Progresses through the image by writing images, frames, or raw individual chunks. This is constructed through Encoder::write_header().

FIXME: Writing of animated chunks might be clearer if we had an adapter that you would call to guarantee the next image to be prefaced with a fcTL-chunk, and all other chunks would be guaranteed to be IDAT/not affected by APNG’s frame control.

Fields

w: W

The underlying writer.

info: PartialInfo

The local version of the Info struct.

options: Options

Global encoding options.

images_written: u64

The total number of image frames, counting all consecutive IDAT and fdAT chunks.

animation_written: u32

The total number of animation frames, that is equivalent to counting fcTL chunks.

iend_written: bool

A flag to note when the IEND chunk was already added. This is only set on code paths that drop Self to control the destructor.

Implementations

impl<W: Write> Writer<W>

fn new(w: W, info: PartialInfo, options: Options) -> Writer<W>

fn init(self, info: &Info<'_>) -> Result<Self, EncodingError>

pub fn write_chunk( &mut self, name: ChunkType, data: &[u8], ) -> Result<(), EncodingError>

Write a raw chunk of PNG data.

The chunk will have its CRC calculated and correctly. The data is not filtered in any way, but the chunk needs to be short enough to have its length encoded correctly.

pub fn write_text_chunk<T: EncodableTextChunk>( &mut self, text_chunk: &T, ) -> Result<(), EncodingError>

fn validate_new_image(&self) -> Result<(), EncodingError>

Check if we should allow writing another image.

fn validate_sequence_done(&self) -> Result<(), EncodingError>

const MAX_IDAT_CHUNK_LEN: u32 = 2_147_483_647u32

const MAX_fdAT_CHUNK_LEN: u32 = 2_147_483_643u32

pub fn write_image_data(&mut self, data: &[u8]) -> Result<(), EncodingError>

Writes the next image data.

fn increment_images_written(&mut self)

fn write_iend(&mut self) -> Result<(), EncodingError>

fn should_skip_frame_control_on_default_image(&self) -> bool

fn write_zlib_encoded_idat( &mut self, zlib_encoded: &[u8], ) -> Result<(), EncodingError>

pub fn set_filter(&mut self, filter: FilterType)

Set the used filter type for the following frames.

The default filter is FilterType::Sub which provides a basic prediction algorithm for sample values based on the previous. For a potentially better compression ratio, at the cost of more complex processing, try out FilterType::Paeth.

pub fn set_adaptive_filter(&mut self, adaptive_filter: AdaptiveFilterType)

Set the adaptive filter type for the following frames.

Adaptive filtering attempts to select the best filter for each line based on heuristics which minimize the file size for compression rather than use a single filter for the entire image. The default method is AdaptiveFilterType::NonAdaptive.

pub fn set_frame_delay( &mut self, numerator: u16, denominator: u16, ) -> Result<(), EncodingError>

Set the fraction of time the following frames are going to be displayed, in seconds

If the denominator is 0, it is to be treated as if it were 100 (that is, the numerator then specifies 1/100ths of a second). If the value of the numerator is 0 the decoder should render the next frame as quickly as possible, though viewers may impose a reasonable lower bound.

This method will return an error if the image is not animated.

pub fn set_frame_dimension( &mut self, width: u32, height: u32, ) -> Result<(), EncodingError>

Set the dimension of the following frames.

This function will return an error when:

• The image is not an animated;

• The selected dimension, considering also the current frame position, goes outside the image boundaries;

• One or both the width and height are 0;

pub fn set_frame_position( &mut self, x: u32, y: u32, ) -> Result<(), EncodingError>

Set the position of the following frames.

An error will be returned if:

• The image is not animated;

• The selected position, considering also the current frame dimension, goes outside the image boundaries;

pub fn reset_frame_dimension(&mut self) -> Result<(), EncodingError>

Set the frame dimension to occupy all the image, starting from the current position.

To reset the frame to the full image size reset_frame_position should be called first.

This method will return an error if the image is not animated.

pub fn reset_frame_position(&mut self) -> Result<(), EncodingError>

Set the frame position to (0, 0).

Equivalent to calling set_frame_position(0, 0).

This method will return an error if the image is not animated.

pub fn set_blend_op(&mut self, op: BlendOp) -> Result<(), EncodingError>

Set the blend operation for the following frames.

The blend operation specifies whether the frame is to be alpha blended into the current output buffer content, or whether it should completely replace its region in the output buffer.

See the BlendOp documentation for the possible values and their effects.

Note that for the first frame the two blend modes are functionally equivalent due to the clearing of the output buffer at the beginning of each play.

This method will return an error if the image is not animated.

pub fn set_dispose_op(&mut self, op: DisposeOp) -> Result<(), EncodingError>

Set the dispose operation for the following frames.

The dispose operation specifies how the output buffer should be changed at the end of the delay (before rendering the next frame)

See the DisposeOp documentation for the possible values and their effects.

Note that if the first frame uses DisposeOp::Previous it will be treated as DisposeOp::Background.

This method will return an error if the image is not animated.

pub fn stream_writer(&mut self) -> Result<StreamWriter<'_, W>, EncodingError>

Create a stream writer.

This allows you to create images that do not fit in memory. The default chunk size is 4K, use stream_writer_with_size to set another chunk size.

This borrows the writer which allows for manually appending additional chunks after the image data has been written.

pub fn stream_writer_with_size( &mut self, size: usize, ) -> Result<StreamWriter<'_, W>, EncodingError>

Create a stream writer with custom buffer size.

See stream_writer.

pub fn into_stream_writer( self, ) -> Result<StreamWriter<'static, W>, EncodingError>

Turn this into a stream writer for image data.

This allows you to create images that do not fit in memory. The default chunk size is 4K, use stream_writer_with_size to set another chunk size.

pub fn into_stream_writer_with_size( self, size: usize, ) -> Result<StreamWriter<'static, W>, EncodingError>

Turn this into a stream writer with custom buffer size.

See into_stream_writer.

pub fn finish(self) -> Result<(), EncodingError>

Consume the stream writer with validation.

Unlike a simple drop this ensures that the final chunk was written correctly. When other validation options (chunk sequencing) had been turned on in the configuration then it will also do a check on their correctness before writing the final chunk.

Trait Implementations

impl<W: Write> Drop for Writer<W>

fn drop(&mut self)

Executes the destructor for this type.