Skip to main content

Pixmap

Struct Pixmap 

pub struct Pixmap<'a> { /* private fields */ }

Implementations§

§

impl<'pixels> Pixmap<'pixels>

pub fn new( info: &Handle<SkImageInfo>, pixels: &'pixels mut [u8], row_bytes: usize, ) -> Option<Pixmap<'pixels>>

Creates a Pixmap from info width, height, alpha type, and color type. pixels points to pixels. row_bytes should be info.width() times info.bytes_per_pixel(), or larger.

No parameter checking is performed; it is up to the caller to ensure that pixels and row_bytes agree with info.

The memory lifetime of pixels is managed by the caller. When the Pixmap goes out of scope, the pixel address is unaffected.

The Pixmap may be later modified by Self::reset() to change its size, pixel type, or storage.

  • info width, height, alpha type, color type of the image info
  • pixels pointer to pixels allocated by the caller
  • row_bytes size of one row of pixels; width times pixel size, or larger

Example (C++): https://fiddle.skia.org/c/@Pixmap_reset_2

pub fn reset(&mut self) -> &mut Pixmap<'pixels>

Sets width, height, row bytes to zero; pixel address to null; color type to ColorType::Unknown; and alpha type to AlphaType::Unknown.

The prior pixels are unaffected; it is up to the caller to release pixels memory if desired.

Example (C++): https://fiddle.skia.org/c/@Pixmap_reset

pub fn set_color_space( &mut self, color_space: impl Into<Option<RCHandle<SkColorSpace>>>, ) -> &mut Pixmap<'pixels>

Changes the ColorSpace in the ImageInfo; preserves width, height, alpha type, and color type, and leaves the pixel address and row bytes unchanged. The ColorSpace reference count is incremented.

  • color_space color space moved to the image info

Example (C++): https://fiddle.skia.org/c/@Pixmap_setColorSpace

pub fn extract_subset(&self, area: impl AsRef<IRect>) -> Option<Pixmap<'pixels>>

Sets the subset width, height, pixel address to the intersection of the Pixmap with area, if the intersection is not empty; and returns true. Otherwise, leaves the subset unchanged and returns false.

  • area bounds to intersect with the pixmap

pub fn info(&self) -> &Handle<SkImageInfo>

Returns the width, height, alpha type, color type, and color space.

pub fn row_bytes(&self) -> usize

Returns the row bytes, the interval from one pixel row to the next. Row bytes is at least as large as width() * info().bytes_per_pixel().

Returns zero if the color type is ColorType::Unknown. It is up to the bitmap creator to ensure that row bytes is a useful value.

pub fn addr(&self) -> *const c_void

Returns the pixel address, the base address corresponding to the pixel origin.

It is up to the pixmap creator to ensure that the pixel address is a useful value.

pub fn width(&self) -> i32

Returns the pixel count in each pixel row. Should be equal to or less than row_bytes() / info().bytes_per_pixel().

pub fn height(&self) -> i32

Returns the pixel row count.

pub fn is_empty(&self) -> bool

Returns true if the pixmap is empty (from its ImageInfo).

pub fn dimensions(&self) -> ISize

Returns the dimensions of the pixmap (from its ImageInfo).

pub fn color_type(&self) -> ColorType

Returns the color type.

pub fn alpha_type(&self) -> SkAlphaType

Returns the alpha type.

pub fn color_space(&self) -> Option<RCHandle<SkColorSpace>>

Returns the ColorSpace, the range of colors, associated with the ImageInfo. The returned ColorSpace is immutable.

pub fn is_opaque(&self) -> bool

Returns true if the alpha type is AlphaType::Opaque. Does not check if the color type allows alpha, or if any pixel value has transparency.

pub fn bounds(&self) -> IRect

Returns the integral rectangle from the origin to Self::width() and Self::height().

pub fn row_bytes_as_pixels(&self) -> usize

Returns the number of pixels that fit on a row. Should be greater than or equal to Self::width().

pub fn shift_per_pixel(&self) -> usize

Returns the bit shift converting row bytes to row pixels. Returns zero for ColorType::Unknown.

pub fn compute_byte_size(&self) -> usize

Returns the minimum memory required for pixel storage. Does not include unused memory on the last row when Self::row_bytes_as_pixels() exceeds Self::width(). Returns usize::MAX if the result does not fit in usize. Returns zero if Self::height() or Self::width() is 0. Returns Self::height() times Self::row_bytes() if the color type is ColorType::Unknown.

pub fn compute_is_opaque(&self) -> bool

Returns true if all pixels are opaque. The color type determines how pixels are encoded, and whether a pixel describes alpha. Returns true for color types without alpha in each pixel; for other color types, returns true if all pixels have alpha values equivalent to 1.0 or greater.

For ColorType::RGB565 or ColorType::Gray8: always returns true. For ColorType::Alpha8, ColorType::BGRA8888, ColorType::RGBA8888: returns true if all pixel alpha values are 255. For ColorType::ARGB4444: returns true if all pixel alpha values are 15. For ColorType::RGBAF16: returns true if all pixel alpha values are 1.0 or greater.

Returns false for ColorType::Unknown.

Example (C++): https://fiddle.skia.org/c/@Pixmap_computeIsOpaque

pub fn get_color(&self, p: impl Into<IPoint>) -> Color

Returns the pixel at (p.x, p.y) as an unpremultiplied color. Returns black with alpha if the color type is ColorType::Alpha8.

Input is not validated: out of bounds values of p trigger an assert if built with debug defined; and returns undefined values or may crash if release is defined. Fails if the color type is ColorType::Unknown or the pixel address is null.

The ColorSpace in the ImageInfo is ignored. Some color precision may be lost in the conversion to unpremultiplied color; original pixel data may have additional precision.

  • p pixel position

Example (C++): https://fiddle.skia.org/c/@Pixmap_getColor

pub fn get_color_4f(&self, p: impl Into<IPoint>) -> Color4f

Returns the pixel at (p.x, p.y) as an unpremultiplied color as a Color4f. Returns black with alpha if the color type is ColorType::Alpha8.

Input is not validated: out of bounds values of p trigger an assert if built with debug defined; and returns undefined values or may crash if release is defined. Fails if the color type is ColorType::Unknown or the pixel address is null.

The ColorSpace in the ImageInfo is ignored. Some color precision may be lost in the conversion to unpremultiplied color; original pixel data may have additional precision, though this is less likely than for Self::get_color(). Rounding errors may occur if the underlying type has lower precision.

  • p pixel position

pub fn get_alpha_f(&self, p: impl Into<IPoint>) -> f32

Looks up the pixel at (p.x, p.y) and returns its alpha component, normalized to [0..1]. This is roughly equivalent to get_color().a(), but can be more efficient (and more precise if the pixels store more than 8 bits per component).

  • p pixel position

pub fn addr_at(&self, p: impl Into<IPoint>) -> *const c_void

Returns the readable pixel address at (p.x, p.y). Returns null if the pixel ref is null.

Input is not validated: out of bounds values of p trigger an assert if built with debug defined. Returns null if the color type is ColorType::Unknown.

Performs a lookup of pixel size; for better performance, call one of the typed address accessors.

  • p pixel position

pub fn writable_addr(&self) -> *mut c_void

Returns the writable base pixel address.

pub fn writable_addr_at(&self, p: impl Into<IPoint>) -> *mut c_void

Returns the writable pixel address at (p.x, p.y).

Input is not validated: out of bounds values of p trigger an assert if built with debug defined. Returns zero if the color type is ColorType::Unknown.

  • p pixel position

pub fn read_pixels<P>( &self, dst_info: &Handle<SkImageInfo>, pixels: &mut [P], dst_row_bytes: usize, src: impl Into<IPoint>, ) -> bool

Copies a rectangle of pixels to pixels. Copy starts at (src.x, src.y), and does not exceed the pixmap (width(), height()).

dst_info specifies width, height, color type, alpha type, and color space of the destination. dst_row_bytes specifies the gap from one destination row to the next. Returns true if pixels are copied. Returns false if dst_info address equals null, or dst_row_bytes is less than dst_info.min_row_bytes().

Pixels are copied only if pixel conversion is possible. If the pixmap color type is ColorType::Gray8 or ColorType::Alpha8, dst_info.color_type() must match. If the pixmap color type is ColorType::Gray8, dst_info.color_space() must match. If the pixmap alpha type is AlphaType::Opaque, dst_info.alpha_type() must match. If the pixmap color space is None, dst_info.color_space() must match. Returns false if pixel conversion is not possible.

src.x and src.y may be negative to copy only the top or left of the source. Returns false if the pixmap width() or height() is zero or negative. Returns false if abs(src.x) is greater than or equal to the pixmap width(), or if abs(src.y) is greater than or equal to the pixmap height().

  • dst_info destination width, height, color type, alpha type, color space
  • pixels destination pixel storage
  • dst_row_bytes destination row length
  • src source position

pub fn bytes(&self) -> Option<&'pixels [u8]>

Access the underlying pixels as a byte array. This is a rust-skia specific function.

pub fn bytes_mut(&mut self) -> Option<&'pixels mut [u8]>

pub fn pixels<P>(&self) -> Option<&'pixels [P]>
where P: Pixel,

Access the underlying pixels. This is a rust-skia specific function.

The Pixel type must implement the unsafe trait Pixel and must return true in Pixel::matches_color_type() when matched against the ColorType of this Pixmap’s pixels.

pub fn read_pixels_to_pixmap( &self, dst: &mut Pixmap<'_>, src: impl Into<IPoint>, ) -> bool

Copies a rectangle of pixels to dst. Copy starts at src, and does not exceed the pixmap (width(), height()). dst specifies width, height, color type, alpha type, and color space of the destination. Returns true if pixels are copied. Returns false if the destination address is null, or dst.row_bytes() is less than dst.info().min_row_bytes().

Pixels are copied only if pixel conversion is possible. If the pixmap color type is ColorType::Gray8 or ColorType::Alpha8, dst.info().color_type() must match. If the pixmap color type is ColorType::Gray8, dst.info().color_space() must match. If the pixmap alpha type is AlphaType::Opaque, dst.info().alpha_type() must match. If the pixmap color space is None, dst.info().color_space() must match. Returns false if pixel conversion is not possible.

src.x and src.y may be negative to copy only the top or left of the source. Returns false if the pixmap width() or height() is zero or negative. Returns false if abs(src.x) is greater than or equal to the pixmap width(), or if abs(src.y) is greater than or equal to the pixmap height().

  • dst image info and pixel address to write to
  • src source position

pub fn scale_pixels( &self, dst: &mut Pixmap<'_>, sampling: impl Into<SamplingOptions>, ) -> bool

Copies the pixmap to dst, scaling pixels to fit dst.width() and dst.height(), and converting pixels to match dst.color_type() and dst.alpha_type(). Returns true if pixels are copied. Returns false if the destination address is null, or the destination row bytes is less than the destination minimum row bytes.

Pixels are copied only if pixel conversion is possible. If the pixmap color type is ColorType::Gray8 or ColorType::Alpha8, the destination color type must match. If the pixmap color type is ColorType::Gray8, the destination color space must match. If the pixmap alpha type is AlphaType::Opaque, the destination alpha type must match. If the pixmap color space is None, the destination color space must match. Returns false if pixel conversion is not possible.

Returns false if the pixmap width() or height() is zero or negative.

  • dst image info and pixel address to write to
  • sampling sampling options

Example (C++): https://fiddle.skia.org/c/@Pixmap_scalePixels

pub fn erase(&mut self, color: impl Into<Color>, subset: Option<&IRect>) -> bool

Writes color to pixels bounded by subset; returns true on success. Returns false if the color type is ColorType::Unknown, or if subset does not intersect the bounds. If subset is None, writes color to pixels inside the bounds.

  • color sRGB unpremultiplied color to write
  • subset bounding integer rectangle of pixels to write

Example (C++): https://fiddle.skia.org/c/@Pixmap_erase

pub fn erase_4f( &mut self, color: impl AsRef<Color4f>, subset: Option<&IRect>, ) -> bool

Writes color to pixels bounded by subset; returns true on success. If subset is None, writes color to pixels inside the bounds. Returns false if the color type is ColorType::Unknown, if subset is not None and does not intersect the bounds, or if subset is None and the bounds is empty.

  • color unpremultiplied color to write
  • subset bounding integer rectangle of pixels to write; may be None
§

impl Pixmap<'_>

pub fn encode( &self, format: SkEncodedImageFormat, quality: impl Into<Option<u32>>, ) -> Option<Vec<u8>>

Encodes the pixels of this pixmap into an image in the given format, and returns the encoded bytes, or None if the format is not supported or the encoding fails.

  • quality An encoder specific value in the range 0..=100. None selects the default of 100.

Trait Implementations§

§

impl Debug for Pixmap<'_>

§

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

Formats the value using the given formatter. Read more
§

impl Default for Pixmap<'_>

§

fn default() -> Pixmap<'_>

Returns the “default value” for a type. Read more

Auto Trait Implementations§

§

impl<'a> !Freeze for Pixmap<'a>

§

impl<'a> !RefUnwindSafe for Pixmap<'a>

§

impl<'a> !Send for Pixmap<'a>

§

impl<'a> !Sync for Pixmap<'a>

§

impl<'a> !UnwindSafe for Pixmap<'a>

§

impl<'a> Unpin for Pixmap<'a>

§

impl<'a> UnsafeUnpin for Pixmap<'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> NoneValue for T
where T: Default,

§

type NoneType = T

§

fn null_value() -> T

The none-equivalent value.
§

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