Skip to main content

Codec

Struct Codec 

pub struct Codec<'a> { /* private fields */ }
Expand description

Abstraction layer directly on top of an image codec.

Implementations§

§

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>
where T: Read + Seek,

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

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

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>

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

Whether the encoded input uses 16 or more bits per component.

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

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>

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_subset In/out parameter. As input, a desired subset of the original bounds (as specified by Codec::info()). If Some is returned, desired_subset may have been modified to a subset which is supported. Although a particular change may have been made to desired_subset to create something supported, it is possible other changes could result in a valid subset. If None is 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

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

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.

  • info A description of the format (config, size) expected by the caller. This can simply be identical to the info returned by Codec::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 return Result::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::ColorSpace that maps to the ICC profile reported by getICCProfile(), 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().

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

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>

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

If decoding to YUV is supported, this returns Some. Otherwise, this returns None and the caller will ignore the output parameter.

  • supported_data_types Indicates 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 in supported_data_types, this method returns None.

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

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

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_info Info of the destination. If the dimensions do not match those of Codec::info(), this implies a scale.
  • dst Memory to write to. Needs to be large enough to hold the subset, if present, or the full image as described in dst_info.
  • options Contains 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>)

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

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_info Info of the destination. If the dimensions do not match those of Codec::info(), this implies a scale.
  • options Contains 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

Write the next count_lines scanlines into dst.

Not valid to call before calling Codec::start_scanline_decode().

  • dst Must be large enough to hold count_lines scanlines of size row_bytes.
  • count_lines Number of lines to write.
  • row_bytes Number of bytes per row. Must be large enough to hold a scanline based on the ImageInfo used 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

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

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

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

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

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>

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>

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:

  1. Still (non-animated) images.
  2. 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

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§

§

impl Debug for Codec<'_>

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more

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> 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
§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert 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>

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

Convert &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)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
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.

§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

§

impl<T, S> SimdFrom<T, S> for T
where S: Simd,

§

fn simd_from(_simd: S, value: T) -> T

§

impl<F, T, S> SimdInto<T, S> for F
where T: SimdFrom<F, S>, S: Simd,

§

fn simd_into(self, simd: S) -> T

Source§

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

Source§

type Error = !

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

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

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

Source§

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

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more