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>
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>
sourcepub fn set_animated(
&mut self,
num_frames: u32,
num_plays: u32,
) -> Result<(), 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.
sourcepub fn set_sep_def_img(
&mut self,
sep_def_img: bool,
) -> Result<(), EncodingError>
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
).
sourcepub fn set_palette<T: Into<Cow<'a, [u8]>>>(&mut self, palette: T)
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.
sourcepub fn set_trns<T: Into<Cow<'a, [u8]>>>(&mut self, trns: T)
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.
sourcepub fn set_source_gamma(&mut self, source_gamma: ScaledFloat)
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.
sourcepub fn set_source_chromaticities(
&mut self,
source_chromaticities: SourceChromaticities,
)
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.
sourcepub fn set_source_srgb(&mut self, rendering_intent: SrgbRenderingIntent)
pub fn set_source_srgb(&mut self, rendering_intent: SrgbRenderingIntent)
Mark the image data as conforming to the SRGB color space with the specified rendering intent.
Any ICC profiles will be ignored.
Source gamma and chromaticities will be written only if they’re set to fallback values specified in 11.3.2.5.
sourcepub fn write_header(self) -> Result<Writer<W>, EncodingError>
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
.
sourcepub fn set_color(&mut self, color: ColorType)
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.
sourcepub fn set_compression(&mut self, compression: Compression)
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”.
sourcepub fn set_filter(&mut self, filter: FilterType)
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
.
sourcepub fn set_adaptive_filter(&mut self, adaptive_filter: AdaptiveFilterType)
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
.
sourcepub fn set_frame_delay(
&mut self,
numerator: u16,
denominator: u16,
) -> Result<(), EncodingError>
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
)
sourcepub fn set_blend_op(&mut self, op: BlendOp) -> Result<(), EncodingError>
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
)
sourcepub fn set_dispose_op(&mut self, op: DisposeOp) -> Result<(), EncodingError>
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>)
sourcepub fn add_text_chunk(
&mut self,
keyword: String,
text: String,
) -> Result<(), EncodingError>
pub fn add_text_chunk( &mut self, keyword: String, text: String, ) -> Result<(), EncodingError>
Convenience function to add tEXt chunks to Info
struct
sourcepub fn add_ztxt_chunk(
&mut self,
keyword: String,
text: String,
) -> Result<(), EncodingError>
pub fn add_ztxt_chunk( &mut self, keyword: String, text: String, ) -> Result<(), EncodingError>
Convenience function to add zTXt chunks to Info
struct
sourcepub fn add_itxt_chunk(
&mut self,
keyword: String,
text: String,
) -> Result<(), EncodingError>
pub fn add_itxt_chunk( &mut self, keyword: String, text: String, ) -> Result<(), EncodingError>
sourcepub fn validate_sequence(&mut self, validate: bool)
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.)