Struct Codec
pub struct Codec<'a> { /* private fields */ }Expand description
Abstraction layer directly on top of an image codec.
Implementations§
§impl Codec<'_>
impl Codec<'_>
pub fn from_stream<'a, T>(
stream: &'a mut T,
decoders: &[Handle<SkCodecs_Decoder>],
selection_policy: impl Into<Option<SkCodec_SelectionPolicy>>,
) -> Result<Codec<'a>, SkCodec_Result>
pub fn from_stream<'a, T>( stream: &'a mut T, decoders: &[Handle<SkCodecs_Decoder>], selection_policy: impl Into<Option<SkCodec_SelectionPolicy>>, ) -> Result<Codec<'a>, SkCodec_Result>
If this stream represents an encoded image that we know how to decode, return a Codec
that can decode it. Otherwise return an error Result explaining the reason for the
failure.
As stated above, this call must be able to peek or read MinBufferedBytesNeeded to determine
the correct format, and then start reading from the beginning. First it will attempt to peek,
and it assumes that if less than MinBufferedBytesNeeded bytes (but more than zero) are
returned, this is because the stream is shorter than this, so falling back to reading would
not provide more data. If peek() returns zero bytes, this call will instead attempt to
read(). This will require that the stream can be rewind()ed.
The returned Result is set to either Result::Success if a Codec is returned or a
reason for the failure if an error is returned.
pub fn from_data(data: impl Into<RCHandle<SkData>>) -> Option<Codec<'static>>
pub fn from_data(data: impl Into<RCHandle<SkData>>) -> Option<Codec<'static>>
If this data represents an encoded image that we know how to decode, return a Codec that
can decode it. Otherwise return None.
pub fn from_data_with_decoders(
data: impl Into<RCHandle<SkData>>,
decoders: &[Handle<SkCodecs_Decoder>],
) -> Option<Codec<'static>>
pub fn from_data_with_decoders( data: impl Into<RCHandle<SkData>>, decoders: &[Handle<SkCodecs_Decoder>], ) -> Option<Codec<'static>>
If this data represents an encoded image that we know how to decode, return a Codec that
can decode it. Otherwise return None.
pub fn info(&self) -> Handle<SkImageInfo>
pub fn info(&self) -> Handle<SkImageInfo>
Return a reasonable ImageInfo to decode into.
If the image has an ICC profile that does not map to an crate::ColorSpace, the returned
ImageInfo will use SRGB.
pub fn dimensions(&self) -> ISize
pub fn bounds(&self) -> IRect
pub fn has_high_bit_depth_encoded_data(&self) -> bool
pub fn has_high_bit_depth_encoded_data(&self) -> bool
Whether the encoded input uses 16 or more bits per component.
pub fn origin(&self) -> EncodedOrigin
pub fn origin(&self) -> EncodedOrigin
Returns the image orientation stored in the EXIF data.
If there is no EXIF data, or if we cannot read the EXIF data, returns
EncodedOrigin::TopLeft.
pub fn get_scaled_dimensions(&self, desired_scale: f32) -> ISize
pub fn get_scaled_dimensions(&self, desired_scale: f32) -> ISize
Return a size that approximately supports the desired scale factor. The codec may not be able to scale efficiently to the exact scale factor requested, so return a size that approximates that scale. The returned value is the codec’s suggestion for the closest valid scale that it can natively support.
pub fn valid_subset(&self, desired_subset: impl AsRef<IRect>) -> Option<IRect>
pub fn valid_subset(&self, desired_subset: impl AsRef<IRect>) -> Option<IRect>
Return (via desired_subset) a subset which can be decoded from this codec, or None if
this codec cannot decode subsets or anything similar to desired_subset.
desired_subsetIn/out parameter. As input, a desired subset of the original bounds (as specified byCodec::info()). IfSomeis returned,desired_subsetmay have been modified to a subset which is supported. Although a particular change may have been made todesired_subsetto create something supported, it is possible other changes could result in a valid subset. IfNoneis returned,desired_subset’s value is undefined.
Returns Some if this codec supports decoding desired_subset (as returned, potentially
modified).
pub fn encoded_format(&self) -> SkEncodedImageFormat
pub fn encoded_format(&self) -> SkEncodedImageFormat
Format of the encoded data.
pub fn get_pixels_with_options(
&mut self,
info: &Handle<SkImageInfo>,
pixels: &mut [u8],
row_bytes: usize,
options: Option<&Options>,
) -> SkCodec_Result
pub fn get_pixels_with_options( &mut self, info: &Handle<SkImageInfo>, pixels: &mut [u8], row_bytes: usize, options: Option<&Options>, ) -> SkCodec_Result
Decode into the given pixels, a block of memory of size at least
([ImageInfo::height()] - 1) * row_bytes + ([ImageInfo::width()] * bytes_per_pixel).
Repeated calls to this function should give the same results, allowing the PixelRef to be immutable.
-
infoA description of the format (config, size) expected by the caller. This can simply be identical to the info returned byCodec::info().This contract also allows the caller to specify different output-configs, which the implementation can decide to support or not.
A size that does not match
Codec::info()implies a request to scale. If the generator cannot perform this scale, it will returnResult::InvalidScale.If the info contains a non-null
crate::ColorSpace, the codec will perform the appropriate color space transformation.If the caller passes in the
crate::ColorSpacethat maps to the ICC profile reported bygetICCProfile(), the color space transformation is a no-op.If the caller passes a null
crate::ColorSpace, no color space transformation will be done.
If a scanline decode is in progress, scanline mode will end, requiring the client to call
Codec::start_scanline_decode() in order to return to decoding scanlines.
For certain codecs, reading into a smaller bitmap than the original dimensions may not produce correct results (e.g. animated webp).
Returns Result::Success, or another value explaining the type of failure.
pub unsafe fn get_pixels(
&mut self,
info: &Handle<SkImageInfo>,
pixels: *mut c_void,
row_bytes: usize,
) -> SkCodec_Result
👎Deprecated since 0.33.1: Use the safe variant get_pixels_with_options().
pub unsafe fn get_pixels( &mut self, info: &Handle<SkImageInfo>, pixels: *mut c_void, row_bytes: usize, ) -> SkCodec_Result
Use the safe variant get_pixels_with_options().
Simplified version of Codec::get_pixels_with_options() that uses the default
Options.
pub unsafe fn get_pixels_to_pixmap(
&mut self,
pixmap: &Pixmap<'_>,
options: Option<&Options>,
) -> SkCodec_Result
pub unsafe fn get_pixels_to_pixmap( &mut self, pixmap: &Pixmap<'_>, options: Option<&Options>, ) -> SkCodec_Result
Decode into the given Pixmap. See Codec::get_pixels_with_options() for details.
pub fn get_image<'a>(
&mut self,
info: impl Into<Option<Handle<SkImageInfo>>>,
options: impl Into<Option<&'a Options>>,
) -> Result<RCHandle<SkImage>, SkCodec_Result>
pub fn get_image<'a>( &mut self, info: impl Into<Option<Handle<SkImageInfo>>>, options: impl Into<Option<&'a Options>>, ) -> Result<RCHandle<SkImage>, SkCodec_Result>
Return an image containing the pixels. If the codec’s origin is not “upper left”, this will rotate the output image accordingly.
pub fn query_yuva_info(
&self,
supported_data_types: &Handle<SkYUVAPixmapInfo_SupportedDataTypes>,
) -> Option<Handle<SkYUVAPixmapInfo>>
pub fn query_yuva_info( &self, supported_data_types: &Handle<SkYUVAPixmapInfo_SupportedDataTypes>, ) -> Option<Handle<SkYUVAPixmapInfo>>
If decoding to YUV is supported, this returns Some. Otherwise, this returns None and the
caller will ignore the output parameter.
supported_data_typesIndicates the data type/planar config combinations that are supported by the caller. If the generator supports decoding to YUV(A), but not as a type insupported_data_types, this method returnsNone.
The returned YUVAPixmapInfo specifies the planar configuration, subsampling, orientation,
chroma siting, plane color types, and row bytes.
pub fn get_yuva_planes(
&mut self,
pixmaps: &Handle<SkYUVAPixmaps>,
) -> SkCodec_Result
pub fn get_yuva_planes( &mut self, pixmaps: &Handle<SkYUVAPixmaps>, ) -> SkCodec_Result
Returns Result::Success, or another value explaining the type of failure. This always
attempts to perform a full decode. To get the planar configuration without decoding use
Codec::query_yuva_info().
pixmapsContains preallocated pixmaps configured according to a successful call toCodec::query_yuva_info().
pub fn start_incremental_decode<'a>(
&mut self,
dst_info: &Handle<SkImageInfo>,
dst: &mut [u8],
row_bytes: usize,
options: impl Into<Option<&'a Options>>,
) -> SkCodec_Result
pub fn start_incremental_decode<'a>( &mut self, dst_info: &Handle<SkImageInfo>, dst: &mut [u8], row_bytes: usize, options: impl Into<Option<&'a Options>>, ) -> SkCodec_Result
Prepare for an incremental decode with the specified options.
This may require a rewind.
If Result::IncompleteInput is returned, may be called again after more data has been
provided to the source stream.
dst_infoInfo of the destination. If the dimensions do not match those ofCodec::info(), this implies a scale.dstMemory to write to. Needs to be large enough to hold the subset, if present, or the full image as described indst_info.optionsContains decoding options, including if memory is zero initialized and whether to decode a subset.
Returns an enum representing success or reason for failure.
pub fn incremental_decode(&mut self) -> (SkCodec_Result, Option<usize>)
pub fn incremental_decode(&mut self) -> (SkCodec_Result, Option<usize>)
Start/continue the incremental decode.
Not valid to call before a call to Codec::start_incremental_decode() returns
Result::Success.
If Result::IncompleteInput is returned, may be called again after more data has been
provided to the source stream.
Unlike Codec::get_pixels_with_options and Codec::get_scanlines(), this does not do
any filling. This is left up to the caller, since they may be skipping lines or continuing
the decode later. In the latter case, they may choose to initialize all lines first, or only
initialize the remaining lines after the first call.
The returned value is the total number of lines initialized, and is only Some if this
method returns Result::IncompleteInput. Otherwise the implementation may not set it. Note
that some implementations may have initialized this many rows, but not necessarily finished
those rows (e.g. interlaced PNG). This may be useful for determining what rows the client
needs to initialize.
Returns Result::Success if all lines requested in Codec::start_incremental_decode()
have been completely decoded. Result::IncompleteInput otherwise.
pub fn start_scanline_decode<'a>(
&mut self,
dst_info: &Handle<SkImageInfo>,
options: impl Into<Option<&'a Options>>,
) -> SkCodec_Result
pub fn start_scanline_decode<'a>( &mut self, dst_info: &Handle<SkImageInfo>, options: impl Into<Option<&'a Options>>, ) -> SkCodec_Result
Prepare for a scanline decode with the specified options.
After this call, this class will be ready to decode the first scanline.
This must be called in order to call Codec::get_scanlines() or
Codec::skip_scanlines().
This may require rewinding the stream.
Not all Codecs support this.
dst_infoInfo of the destination. If the dimensions do not match those ofCodec::info(), this implies a scale.optionsContains decoding options, including if memory is zero initialized.
Returns an enum representing success or reason for failure.
pub fn get_scanlines(
&mut self,
dst: &mut [u8],
count_lines: usize,
row_bytes: usize,
) -> usize
pub fn get_scanlines( &mut self, dst: &mut [u8], count_lines: usize, row_bytes: usize, ) -> usize
Write the next count_lines scanlines into dst.
Not valid to call before calling Codec::start_scanline_decode().
dstMust be large enough to holdcount_linesscanlines of sizerow_bytes.count_linesNumber of lines to write.row_bytesNumber of bytes per row. Must be large enough to hold a scanline based on theImageInfoused to create this object.
Returns the number of lines successfully decoded. If this value is less than count_lines,
this will fill the remaining lines with a default value.
pub fn skip_scanlines(&mut self, count_lines: usize) -> bool
pub fn skip_scanlines(&mut self, count_lines: usize) -> bool
Skip count_lines scanlines.
Not valid to call before calling Codec::start_scanline_decode().
The default version just calls onGetScanlines and discards the dst. NOTE: If skipped lines
are the only lines with alpha, this default will make reallyHasAlpha return true, when it
could have returned false.
Returns true if the scanlines were successfully skipped, false on failure. Possible
reasons for failure include: an incomplete input image stream; calling this function before
calling Codec::start_scanline_decode(); if count_lines is so large that it moves the
current scanline past the end of the image.
pub fn scanline_order(&self) -> SkCodec_SkScanlineOrder
pub fn scanline_order(&self) -> SkCodec_SkScanlineOrder
An enum representing the order in which scanlines will be returned by the scanline decoder.
This is undefined before Codec::start_scanline_decode() is called.
pub fn next_scanline(&self) -> i32
pub fn next_scanline(&self) -> i32
Returns the y-coordinate of the next row to be returned by the scanline decoder.
This will equal the current scanline, except in the case of strangely encoded image types (bottom-up bmps).
Results are undefined when not in scanline decoding mode.
pub fn outbound_scanline(&self, input_scanline: i32) -> i32
pub fn outbound_scanline(&self, input_scanline: i32) -> i32
Returns the output y-coordinate of the row that corresponds to an input y-coordinate. The input y-coordinate represents where the scanline is located in the encoded data.
This will equal input_scanline, except in the case of strangely encoded image types
(bottom-up bmps, interlaced gifs).
pub fn get_frame_count(&mut self) -> usize
pub fn get_frame_count(&mut self) -> usize
Return the number of frames in the image.
May require reading through the stream.
Note that some codecs may be unable to gather FrameInfo for all frames in case of
Result::IncompleteInput. For such codecs Codec::get_frame_count() may initially
report a low frame count. After the underlying stream provides additional data, then calling
Codec::get_frame_count() again may return an updated, increased frame count.
pub fn get_frame_info(&mut self, index: usize) -> Option<FrameInfo>
pub fn get_frame_info(&mut self, index: usize) -> Option<FrameInfo>
Return info about a single frame.
Does not read through the stream, so it should be called after Codec::get_frame_count()
to parse any frames that have not already been parsed.
Only supported by animated (multi-frame) codecs. Note that this is a property of the codec
(the Codec subclass), not the image.
To elaborate, some codecs support animation (e.g. GIF). Others do not (e.g. BMP). Animated
codecs can still represent single frame images. Calling Codec::get_frame_info()(0, etc)
will return Some for a single frame GIF even if the overall image is not animated (in that
the pixels on screen do not change over time). When incrementally decoding a GIF image, we
might only know that there’s a single frame so far.
For non-animated Codec subclasses, it’s sufficient but not necessary for this method to
always return None.
pub fn get_repetition_count(&mut self) -> Option<usize>
pub fn get_repetition_count(&mut self) -> Option<usize>
Return the number of times to repeat, if this image is animated. This number does not include the first play through of each frame. For example, a repetition count of 4 means that each frame is played 5 times and then the animation stops.
It can return None, meaning that the animation should loop forever.
May require reading the stream to find the repetition count.
As such, future decoding calls may require a rewind.
Codec::get_repetition_count() will return Some(0) in two cases:
- Still (non-animated) images.
- Animated images that only play the animation once (i.e. that don’t repeat the animation).
Codec::is_animated() can be used to disambiguate between these two cases.
pub fn is_animated(&mut self) -> SkCodec_IsAnimated
pub fn is_animated(&mut self) -> SkCodec_IsAnimated
Returns whether the full input is expected to contain an animated image (i.e. more than 1
image frame). This can be used to disambiguate the meaning of
Codec::get_repetition_count() returning Some(0) (see
Codec::get_repetition_count()’s doc comment for more details).
Note that in some codecs Codec::get_frame_count() only returns the number of frames for
which all the metadata has been already successfully decoded. Therefore for a partial input
Codec::is_animated() may return IsAnimated::Yes, even though
Codec::get_frame_count() may temporarily return 1 until more of the input is available.
When handling partial input, some codecs may not know until later (e.g. until encountering
additional image frames) whether the given image has more than one frame. Such codecs may
initially return IsAnimated::Unknown and only later give a definitive “yes” or “no”
answer. GIF format is one example where this may happen.
Other codecs may be able to decode the information from the metadata present before the first image frame. Such codecs should be able to give a definitive “yes” or “no” answer as soon as they are constructed. PNG format is one example where this happens.
Trait Implementations§
Auto Trait Implementations§
impl<'a> !RefUnwindSafe for Codec<'a>
impl<'a> !Send for Codec<'a>
impl<'a> !Sync for Codec<'a>
impl<'a> !UnwindSafe for Codec<'a>
impl<'a> Freeze for Codec<'a>
impl<'a> Unpin for Codec<'a>
impl<'a> UnsafeUnpin for Codec<'a>
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can
then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be
further downcast into Rc<ConcreteType> where ConcreteType implements Trait.§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &Any’s vtable from &Trait’s.§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &mut Any’s vtable from &mut Trait’s.