Struct Encoder

pub struct Encoder<'a, W: Write> { /* private fields */ }

PNG Encoder.

This configures the PNG format options such as animation chunks, palette use, color types, auxiliary chunks etc.

FIXME: Configuring APNG might be easier (less individual errors) if we had an adapter which borrows this mutably but guarantees that info.frame_control is not None.

Implementations

impl<'a, W: Write> Encoder<'a, W>

pub fn new(w: W, width: u32, height: u32) -> Encoder<'static, W>

pub fn with_info(w: W, info: Info<'a>) -> Result<Encoder<'a, W>, EncodingError>

pub fn set_animated( &mut self, num_frames: u32, num_plays: u32, ) -> Result<(), EncodingError>

Specify that the image is animated.

num_frames controls how many frames the animation has, while num_plays controls how many times the animation should be repeated until it stops, if it’s zero then it will repeat infinitely.

When this method is returns successfully then the images written will be encoded as fdAT chunks, except for the first image that is still encoded as IDAT. You can control if the first frame should be treated as an animation frame with Encoder::set_sep_def_img().

This method returns an error if num_frames is 0.

pub fn set_sep_def_img( &mut self, sep_def_img: bool, ) -> Result<(), EncodingError>

Mark the first animated frame as a ‘separate default image’.

In APNG each animated frame is preceded by a special control chunk, fcTL. It’s up to the encoder to decide if the first image, the standard IDAT data, should be part of the animation by emitting this chunk or by not doing so. A default image that is not part of the animation is often interpreted as a thumbnail.

This method will return an error when animation control was not configured (which is done by calling Encoder::set_animated).

pub fn set_palette<T: Into<Cow<'a, [u8]>>>(&mut self, palette: T)

Sets the raw byte contents of the PLTE chunk. This method accepts both borrowed and owned byte data.

pub fn set_trns<T: Into<Cow<'a, [u8]>>>(&mut self, trns: T)

Sets the raw byte contents of the tRNS chunk. This method accepts both borrowed and owned byte data.

pub fn set_source_gamma(&mut self, source_gamma: ScaledFloat)

Set the display gamma of the source system on which the image was generated or last edited.

pub fn set_source_chromaticities( &mut self, source_chromaticities: SourceChromaticities, )

Set the chromaticities for the source system’s display channels (red, green, blue) and the whitepoint of the source system on which the image was generated or last edited.

pub fn set_srgb(&mut self, rendering_intent: SrgbRenderingIntent)

Mark the image data as conforming to the SRGB color space with the specified rendering intent.

Matching source gamma and chromaticities chunks are added automatically. Any manually specified source gamma or chromaticities will be ignored.

pub fn write_header(self) -> Result<Writer<W>, EncodingError>

Start encoding by writing the header data.

The remaining data can be supplied by methods on the returned Writer.

pub fn set_color(&mut self, color: ColorType)

Set the color of the encoded image.

These correspond to the color types in the png IHDR data that will be written. The length of the image data that is later supplied must match the color type, otherwise an error will be emitted.

pub fn set_depth(&mut self, depth: BitDepth)

Set the indicated depth of the image data.

pub fn set_compression(&mut self, compression: Compression)

Set compression parameters.

Accepts a Compression or any type that can transform into a Compression. Notably deflate::Compression and deflate::CompressionOptions which “just work”.

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

Set the used filter type.

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.

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 every frame is going to be displayed, in seconds.

Note that this parameter can be set for each individual frame after Encoder::write_header is called. (see Writer::set_frame_delay)

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.

The default value is 0 for both the numerator and denominator.

This method will return an error if the image is not animated. (see set_animated)

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

Set the blend operation for every frame.

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.

Note that this parameter can be set for each individual frame after write_header is called. (see Writer::set_blend_op)

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.

The default value is BlendOp::Source.

This method will return an error if the image is not animated. (see set_animated)

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

Set the dispose operation for every frame.

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

Note that this parameter can be set for each individual frame after write_header is called (see Writer::set_dispose_op)

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.

The default value is DisposeOp::None.

This method will return an error if the image is not animated. (see set_animated)

pub fn set_pixel_dims(&mut self, pixel_dims: Option<PixelDimensions>)

pub fn add_text_chunk( &mut self, keyword: String, text: String, ) -> Result<(), EncodingError>

Convenience function to add tEXt chunks to Info struct

pub fn add_ztxt_chunk( &mut self, keyword: String, text: String, ) -> Result<(), EncodingError>

Convenience function to add zTXt chunks to Info struct

pub fn add_itxt_chunk( &mut self, keyword: String, text: String, ) -> Result<(), EncodingError>

Convenience function to add iTXt chunks to Info struct

This function only sets the keyword and text field of the iTXt chunk. To set the other fields, create a ITXtChunk directly, and then encode it to the output stream.

pub fn validate_sequence(&mut self, validate: bool)

Validate the written image sequence.

When validation is turned on (it’s turned off by default) then attempts to write more than one IDAT image or images beyond the number of frames indicated in the animation control chunk will fail and return an error result instead. Attempts to finish the image with missing frames will also return an error.

(It’s possible to circumvent these checks by writing raw chunks instead.)