Struct png::Encoder

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

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§

source§

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

source

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

source

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

source

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.

source

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).

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

Set the indicated depth of the image data.

source

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”.

source

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.

source

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.

source

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)

source

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)

source

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)

source

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

source

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

Convenience function to add tEXt chunks to Info struct

source

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

Convenience function to add zTXt chunks to Info struct

source

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.

source

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.)

Auto Trait Implementations§

§

impl<'a, W> Freeze for Encoder<'a, W>
where W: Freeze,

§

impl<'a, W> RefUnwindSafe for Encoder<'a, W>
where W: RefUnwindSafe,

§

impl<'a, W> Send for Encoder<'a, W>
where W: Send,

§

impl<'a, W> Sync for Encoder<'a, W>
where W: Sync,

§

impl<'a, W> Unpin for Encoder<'a, W>
where W: Unpin,

§

impl<'a, W> UnwindSafe for Encoder<'a, W>
where W: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.