Type Alias freya_engine::prelude::Surface

pub type Surface = RCHandle<SkSurface>;

Surface is responsible for managing the pixels that a canvas draws into. The pixels can be allocated either in CPU memory (a raster surface) or on the GPU (a RenderTarget surface). Surface takes care of allocating a Canvas that will draw into the surface. Call surface_get_canvas() to use that canvas (but don’t delete it, it is owned by the surface). Surface always has non-zero dimensions. If there is a request for a new surface, and either of the requested dimensions are zero, then None will be returned.

Aliased Type

struct Surface(/* private fields */);

Implementations

impl RCHandle<SkSurface>

pub fn new_raster_direct<'pixels>( image_info: &Handle<SkImageInfo>, pixels: &'pixels mut [u8], row_bytes: impl Into<Option<usize>>, surface_props: Option<&SurfaceProps> ) -> Option<Borrows<'pixels, RCHandle<SkSurface>>>

👎Deprecated since 0.64.0: use surfaces::wrap_pixels()

Allocates raster Surface. Canvas returned by Surface draws directly into pixels.

Surface is returned if all parameters are valid. Valid parameters include: info dimensions are greater than zero; info contains crate::ColorType and [crate::AlphaType] supported by raster surface; pixels is not None; row_bytes is large enough to contain info width pixels of crate::ColorType.

Pixel buffer size should be info height times computed row_bytes. Pixels are not initialized. To access pixels after drawing, [Self::peek_pixels()] or [Self::read_pixels()].

• image_info - width, height, crate::ColorType, [crate::AlphaType], crate::ColorSpace, of raster surface; width and height must be greater than zero
• pixels - pointer to destination pixels buffer
• row_bytes - interval from one Surface row to the next
• surface_props - LCD striping orientation and setting for device independent fonts; may be None Returns: Surface if all parameters are valid; otherwise, None

pub fn new_raster( image_info: &Handle<SkImageInfo>, row_bytes: impl Into<Option<usize>>, surface_props: Option<&SurfaceProps> ) -> Option<RCHandle<SkSurface>>

👎Deprecated since 0.64.0: use surfaces::raster()

Allocates raster Surface. Canvas returned by Surface draws directly into pixels. Allocates and zeroes pixel memory. Pixel memory size is image_info.height() times row_bytes, or times image_info.min_row_bytes() if row_bytes is zero. Pixel memory is deleted when Surface is deleted.

Surface is returned if all parameters are valid. Valid parameters include: info dimensions are greater than zero; info contains crate::ColorType and [crate::AlphaType] supported by raster surface; row_bytes is large enough to contain info width pixels of crate::ColorType, or is zero.

If row_bytes is zero, a suitable value will be chosen internally.

• image_info - width, height, crate::ColorType, [crate::AlphaType], crate::ColorSpace, of raster surface; width and height must be greater than zero
• row_bytes - interval from one Surface row to the next; may be zero
• surface_props - LCD striping orientation and setting for device independent fonts; may be None Returns: Surface if all parameters are valid; otherwise, None

pub fn new_raster_n32_premul( size: impl Into<ISize> ) -> Option<RCHandle<SkSurface>>

👎Deprecated since 0.64.0: use surfaces::raster_n32_premul()

Allocates raster Surface. Canvas returned by Surface draws directly into pixels. Allocates and zeroes pixel memory. Pixel memory size is height times width times four. Pixel memory is deleted when Surface is deleted.

Internally, sets [ImageInfo] to width, height, native color type, and [crate::AlphaType::Premul].

Surface is returned if width and height are greater than zero.

Use to create Surface that matches [crate::PMColor], the native pixel arrangement on the platform. Surface drawn to output device skips converting its pixel format.

• width - pixel column count; must be greater than zero
• height - pixel row count; must be greater than zero
• surface_props - LCD striping orientation and setting for device independent fonts; may be None Returns: Surface if all parameters are valid; otherwise, None

impl RCHandle<SkSurface>

pub fn from_backend_texture( context: &mut RCHandle<GrRecordingContext>, backend_texture: &RefHandle<GrBackendTexture>, origin: GrSurfaceOrigin, sample_cnt: impl Into<Option<usize>>, color_type: ColorType, color_space: impl Into<Option<RCHandle<SkColorSpace>>>, surface_props: Option<&SurfaceProps> ) -> Option<RCHandle<SkSurface>>

👎Deprecated since 0.64.0: use gpu::surfaces::wrap_backend_texture()

Wraps a GPU-backed texture into Surface. Caller must ensure the texture is valid for the lifetime of returned Surface. If sample_cnt greater than zero, creates an intermediate MSAA Surface which is used for drawing backend_texture.

Surface is returned if all parameters are valid. backend_texture is valid if its pixel configuration agrees with color_space and context; for instance, if backend_texture has an sRGB configuration, then context must support sRGB, and color_space must be present. Further, backend_texture width and height must not exceed context capabilities, and the context must be able to support back-end textures.

• context - GPU context
• backend_texture - texture residing on GPU
• sample_cnt - samples per pixel, or 0 to disable full scene anti-aliasing
• color_space - range of colors; may be None
• surface_props - LCD striping orientation and setting for device independent fonts; may be None Returns: Surface if all parameters are valid; otherwise, None

pub fn from_backend_render_target( context: &mut RCHandle<GrRecordingContext>, backend_render_target: &Handle<GrBackendRenderTarget>, origin: GrSurfaceOrigin, color_type: ColorType, color_space: impl Into<Option<RCHandle<SkColorSpace>>>, surface_props: Option<&SurfaceProps> ) -> Option<RCHandle<SkSurface>>

👎Deprecated since 0.64.0: use gpu::surfaces::wrap_backend_render_target()

Wraps a GPU-backed buffer into Surface. Caller must ensure backend_render_target is valid for the lifetime of returned Surface.

Surface is returned if all parameters are valid. backend_render_target is valid if its pixel configuration agrees with color_space and context; for instance, if backend_render_target has an sRGB configuration, then context must support sRGB, and color_space must be present. Further, backend_render_target width and height must not exceed context capabilities, and the context must be able to support back-end render targets.

• context - GPU context
• backend_render_target - GPU intermediate memory buffer
• color_space - range of colors
• surface_props - LCD striping orientation and setting for device independent fonts; may be None Returns: Surface if all parameters are valid; otherwise, None

pub fn new_render_target( context: &mut RCHandle<GrRecordingContext>, budgeted: Budgeted, image_info: &Handle<SkImageInfo>, sample_count: impl Into<Option<usize>>, surface_origin: impl Into<Option<GrSurfaceOrigin>>, surface_props: Option<&SurfaceProps>, should_create_with_mips: impl Into<Option<bool>> ) -> Option<RCHandle<SkSurface>>

👎Deprecated since 0.64.0: use gpu::surfaces::render_target()

Returns Surface on GPU indicated by context. Allocates memory for pixels, based on the width, height, and crate::ColorType in [ImageInfo]. budgeted selects whether allocation for pixels is tracked by context. image_info describes the pixel format in crate::ColorType, and transparency in [crate::AlphaType], and color matching in crate::ColorSpace.

sample_count requests the number of samples per pixel. Pass zero to disable multi-sample anti-aliasing. The request is rounded up to the next supported count, or rounded down if it is larger than the maximum supported count.

surface_origin pins either the top-left or the bottom-left corner to the origin.

should_create_with_mips hints that Image returned by [Image::image_snapshot] is mip map.

• context - GPU context
• image_info - width, height, crate::ColorType, [crate::AlphaType], crate::ColorSpace; width, or height, or both, may be zero
• sample_count - samples per pixel, or 0 to disable full scene anti-aliasing
• surface_props - LCD striping orientation and setting for device independent fonts; may be None
• should_create_with_mips - hint that Surface will host mip map images Returns: Surface if all parameters are valid; otherwise, None

impl RCHandle<SkSurface>

pub fn new_null(size: impl Into<ISize>) -> Option<RCHandle<SkSurface>>

👎Deprecated since 0.64.0: use surfaces::null()

Returns Surface without backing pixels. Drawing to Canvas returned from Surface has no effect. Calling [Self::image_snapshot()] on returned Surface returns None.

• width - one or greater
• height - one or greater Returns: Surface if width and height are positive; otherwise, None

example: https://fiddle.skia.org/c/@Surface_MakeNull

pub fn width(&self) -> i32

Returns pixel count in each row; may be zero or greater.

Returns: number of pixel columns

pub fn height(&self) -> i32

Returns pixel row count; may be zero or greater.

Returns: number of pixel rows

pub fn image_info(&mut self) -> Handle<SkImageInfo>

Returns an [ImageInfo] describing the surface.

pub fn generation_id(&mut self) -> u32

Returns unique value identifying the content of Surface. Returned value changes each time the content changes. Content is changed by drawing, or by calling [Self::notify_content_will_change()].

Returns: unique content identifier

example: https://fiddle.skia.org/c/@Surface_notifyContentWillChange

pub fn notify_content_will_change( &mut self, mode: SkSurface_ContentChangeMode ) -> &mut RCHandle<SkSurface>

Notifies that Surface contents will be changed by code outside of Skia. Subsequent calls to [Self::generation_id()] return a different value.

example: https://fiddle.skia.org/c/@Surface_notifyContentWillChange

impl RCHandle<SkSurface>

pub fn recording_context(&self) -> Option<RCHandle<GrRecordingContext>>

Returns the recording context being used by the Surface.

Returns: the recording context, if available; None otherwise

pub fn direct_context(&self) -> Option<RCHandle<GrDirectContext>>

rust-skia helper, not in Skia

pub fn get_backend_texture( &mut self, handle_access: SkSurface_BackendHandleAccess ) -> Option<RefHandle<GrBackendTexture>>

👎Deprecated since 0.64.0: use gpu::surfaces::get_backend_texture()

Retrieves the back-end texture. If Surface has no back-end texture, None is returned.

The returned [gpu::BackendTexture] should be discarded if the Surface is drawn to or deleted.

Returns: GPU texture reference; None on failure

pub fn get_backend_render_target( &mut self, handle_access: SkSurface_BackendHandleAccess ) -> Option<Handle<GrBackendRenderTarget>>

👎Deprecated since 0.64.0: use gpu::surfaces::get_backend_render_target()

Retrieves the back-end render target. If Surface has no back-end render target, None is returned.

The returned gpu::BackendRenderTarget should be discarded if the Surface is drawn to or deleted.

Returns: GPU render target reference; None on failure

pub fn replace_backend_texture( &mut self, backend_texture: &RefHandle<GrBackendTexture>, origin: GrSurfaceOrigin ) -> bool

If the surface was made via [Self::from_backend_texture] then it’s backing texture may be substituted with a different texture. The contents of the previous backing texture are copied into the new texture. Canvas state is preserved. The original sample count is used. The [gpu::BackendFormat] and dimensions of replacement texture must match that of the original.

• backend_texture - the new backing texture for the surface

pub fn replace_backend_texture_with_mode( &mut self, backend_texture: &RefHandle<GrBackendTexture>, origin: GrSurfaceOrigin, mode: impl Into<Option<SkSurface_ContentChangeMode>> ) -> bool

If the surface was made via [Self::from_backend_texture()] then it’s backing texture may be substituted with a different texture. The contents of the previous backing texture are copied into the new texture. Canvas state is preserved. The original sample count is used. The [gpu::BackendFormat] and dimensions of replacement texture must match that of the original.

• backend_texture - the new backing texture for the surface
• mode - Retain or discard current Content

impl RCHandle<SkSurface>

pub fn canvas(&mut self) -> &Canvas

Returns Canvas that draws into Surface. Subsequent calls return the same Canvas. Canvas returned is managed and owned by Surface, and is deleted when Surface is deleted.

Returns: drawing Canvas for Surface

example: https://fiddle.skia.org/c/@Surface_getCanvas

pub fn new_surface( &mut self, image_info: &Handle<SkImageInfo> ) -> Option<RCHandle<SkSurface>>

Returns a compatible Surface, or None. Returned Surface contains the same raster, GPU, or null properties as the original. Returned Surface does not share the same pixels.

Returns None if image_info width or height are zero, or if image_info is incompatible with Surface.

• image_info - width, height, crate::ColorType, [crate::AlphaType], crate::ColorSpace, of Surface; width and height must be greater than zero Returns: compatible Surface or None

example: https://fiddle.skia.org/c/@Surface_makeSurface

pub fn new_surface_with_dimensions( &mut self, dim: impl Into<ISize> ) -> Option<RCHandle<SkSurface>>

Calls [Self::new_surface()] with the same [ImageInfo] as this surface, but with the specified width and height.

pub fn image_snapshot(&mut self) -> RCHandle<SkImage>

Returns Image capturing Surface contents. Subsequent drawing to Surface contents are not captured. Image allocation is accounted for if Surface was created with [gpu::Budgeted::Yes].

Returns: Image initialized with Surface contents

example: https://fiddle.skia.org/c/@Surface_makeImageSnapshot

pub fn image_snapshot_with_bounds( &mut self, bounds: impl AsRef<IRect> ) -> Option<RCHandle<SkImage>>

Like the no-parameter version, this returns an image of the current surface contents. This variant takes a rectangle specifying the subset of the surface that is of interest. These bounds will be sanitized before being used.

• If bounds extends beyond the surface, it will be trimmed to just the intersection of it and the surface.
• If bounds does not intersect the surface, then this returns None.
• If bounds == the surface, then this is the same as calling the no-parameter variant.

example: https://fiddle.skia.org/c/@Surface_makeImageSnapshot_2

pub fn draw( &mut self, canvas: &Canvas, offset: impl Into<Point>, sampling: impl Into<SamplingOptions>, paint: Option<&Handle<SkPaint>> )

Draws Surface contents to canvas, with its top-left corner at (offset.x, offset.y).

If Paint paint is not None, apply [crate::ColorFilter], alpha, [crate::ImageFilter], and [crate::BlendMode].

• canvas - Canvas drawn into
• offset.x - horizontal offset in Canvas
• offset.y - vertical offset in Canvas
• sampling - what technique to use when sampling the surface pixels
• paint - Paint containing [crate::BlendMode], [crate::ColorFilter], [crate::ImageFilter], and so on; or None

example: https://fiddle.skia.org/c/@Surface_draw

pub fn peek_pixels(&mut self) -> Option<Pixmap<'_>>

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

Copies crate::Rect of pixels to dst.

Source crate::Rect corners are (src.x, src.y) and Surface (width(), height()). Destination crate::Rect corners are (0, 0) and (dst.width(), dst.height()). Copies each readable pixel intersecting both rectangles, without scaling, converting to dst_color_type() and dst_alpha_type() if required.

Pixels are readable when Surface is raster, or backed by a GPU.

The destination pixel storage must be allocated by the caller.

Pixel values are converted only if crate::ColorType and [crate::AlphaType] do not match. Only pixels within both source and destination rectangles are copied. dst contents outside crate::Rect intersection are unchanged.

Pass negative values for src.x or src.y to offset pixels across or down destination.

Does not copy, and returns false if:

• Source and destination rectangles do not intersect.
• [Pixmap] pixels could not be allocated.
• dst.row_bytes() is too small to contain one row of pixels.

• dst - storage for pixels copied from Surface
• src_x - offset into readable pixels on x-axis; may be negative
• src_y - offset into readable pixels on y-axis; may be negative Returns: true if pixels were copied

example: https://fiddle.skia.org/c/@Surface_readPixels

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

Copies crate::Rect of pixels from Canvas into dst_pixels.

Source crate::Rect corners are (src.x, src.y) and Surface (width(), height()). Destination crate::Rect corners are (0, 0) and (dst_info.width(), dst_info.height()). Copies each readable pixel intersecting both rectangles, without scaling, converting to dst_info_color_type() and dst_info_alpha_type() if required.

Pixels are readable when Surface is raster, or backed by a GPU.

The destination pixel storage must be allocated by the caller.

Pixel values are converted only if crate::ColorType and [crate::AlphaType] do not match. Only pixels within both source and destination rectangles are copied. dst_pixels contents outside crate::Rect intersection are unchanged.

Pass negative values for src.x or src.y to offset pixels across or down destination.

Does not copy, and returns false if:

• Source and destination rectangles do not intersect.
• Surface pixels could not be converted to dst_info.color_type() or dst_info.alpha_type().
• dst_row_bytes is too small to contain one row of pixels.

• dst_info - width, height, crate::ColorType, and [crate::AlphaType] of dst_pixels
• dst_pixels - storage for pixels; dst_info.height() times dst_row_bytes, or larger
• dst_row_bytes - size of one destination row; dst_info.width() times pixel size, or larger
• src.x - offset into readable pixels on x-axis; may be negative
• src.y - offset into readable pixels on y-axis; may be negative Returns: true if pixels were copied

pub fn read_pixels_to_bitmap( &mut self, bitmap: &Handle<SkBitmap>, src: impl Into<IPoint> ) -> bool

Copies crate::Rect of pixels from Surface into bitmap.

Source crate::Rect corners are (src.x, src.y) and Surface (width(), height()). Destination crate::Rect corners are (0, 0) and (bitmap.width(), bitmap.height()). Copies each readable pixel intersecting both rectangles, without scaling, converting to bitmap.color_type() and bitmap.alpha_type() if required.

Pixels are readable when Surface is raster, or backed by a GPU.

The destination pixel storage must be allocated by the caller.

Pixel values are converted only if crate::ColorType and [crate::AlphaType] do not match. Only pixels within both source and destination rectangles are copied. dst contents outside crate::Rect intersection are unchanged.

Pass negative values for src.x or src.y to offset pixels across or down destination.

Does not copy, and returns false if:

• Source and destination rectangles do not intersect.
• Surface pixels could not be converted to dst.color_type() or dst.alpha_type().
• dst pixels could not be allocated.
• dst.row_bytes() is too small to contain one row of pixels.

• dst - storage for pixels copied from Surface
• src.x - offset into readable pixels on x-axis; may be negative
• src.y - offset into readable pixels on y-axis; may be negative Returns: true if pixels were copied

example: https://fiddle.skia.org/c/@Surface_readPixels_3

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

Copies crate::Rect of pixels from the src [Pixmap] to the Surface.

Source crate::Rect corners are (0, 0) and (src.width(), src.height()). Destination crate::Rect corners are (dst.x, dst.y) and (dst.x + Surface width(), dst.y + Surface height()).

Copies each readable pixel intersecting both rectangles, without scaling, converting to Surface color_type() and Surface alpha_type() if required.

• src - storage for pixels to copy to Surface
• dst.x - x-axis position relative to Surface to begin copy; may be negative
• dst.y - y-axis position relative to Surface to begin copy; may be negative

example: https://fiddle.skia.org/c/@Surface_writePixels

pub fn write_pixels_from_bitmap( &mut self, bitmap: &Handle<SkBitmap>, dst: impl Into<IPoint> )

Copies crate::Rect of pixels from the src [Bitmap] to the Surface.

Source crate::Rect corners are (0, 0) and (src.width(), src.height()). Destination crate::Rect corners are (dst.x, dst.y) and (dst.x+ Surface width(),dst.y + Surface height()).

Copies each readable pixel intersecting both rectangles, without scaling, converting to Surface color_type() and Surface alpha_type() if required.

• src - storage for pixels to copy to Surface
• dst.x - x-axis position relative to Surface to begin copy; may be negative
• dst.y - y-axis position relative to Surface to begin copy; may be negative

example: https://fiddle.skia.org/c/@Surface_writePixels_2

pub fn props(&self) -> &SurfaceProps

Returns [SurfaceProps] for surface.

Returns: LCD striping orientation and setting for device independent fonts

impl RCHandle<SkSurface>

pub fn resolve_msaa(&mut self)

👎Deprecated since 0.65.0: Use gpu::surfaces::resolve_msaa

If a surface is GPU texture backed, is being drawn with MSAA, and there is a resolve texture, this call will insert a resolve command into the stream of gpu commands. In order for the resolve to actually have an effect, the work still needs to be flushed and submitted to the GPU after recording the resolve command. If a resolve is not supported or the Surface has no dirty work to resolve, then this call is a no-op.

This call is most useful when the Surface is created by wrapping a single sampled gpu texture, but asking Skia to render with MSAA. If the client wants to use the wrapped texture outside of Skia, the only way to trigger a resolve is either to call this command or use [Self::flush()].

Trait Implementations

impl<N> AsRef<RCHandle<N>> for RCHandle<N>where N: NativeRefCounted,

fn as_ref(&self) -> &RCHandle<N>

Converts this type into a shared reference of the (usually inferred) input type.

impl<N> Clone for RCHandle<N>where N: NativeRefCounted,

fn clone(&self) -> RCHandle<N>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<H> ConditionallySend for RCHandle<H>where H: NativeRefCountedBase,

RCHandle<H> is conditionally Send and can be sent to another thread when its reference count is 1.

fn can_send(&self) -> bool

Returns true if the handle can be sent to another thread.

fn wrap_send(self) -> Result<Sendable<RCHandle<H>>, RCHandle<H>>

Wrap the handle in a type that can be sent to another thread and unwrapped there.

impl Debug for RCHandle<SkSurface>

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

Formats the value using the given formatter.

impl<N> Drop for RCHandle<N>where N: NativeRefCounted,

fn drop(&mut self)

Executes the destructor for this type.

impl<N> Flattenable for RCHandle<N>where N: NativeFlattenable + NativeRefCountedBase,

fn type_name(&self) -> &CStr

fn serialize(&self) -> RCHandle<SkData>

fn deserialize(data: &[u8]) -> Option<RCHandle<N>>

impl<N> From<&RCHandle<N>> for RCHandle<N>where N: NativeRefCounted,

A reference counted handle is cheap to clone, so we do support a conversion from a reference to a ref counter to an owned handle.

fn from(rch: &RCHandle<N>) -> RCHandle<N>

Converts to this type from the input type.

impl<N> PartialEq<RCHandle<N>> for RCHandle<N>where N: NativeRefCounted + NativePartialEq,

fn eq(&self, rhs: &RCHandle<N>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<N> PointerWrapper<N> for RCHandle<N>where N: NativeRefCounted,

fn wrap(ptr: *mut N) -> Option<RCHandle<N>>

Wraps a native pointer into a wrapper type. Returns None if the pointer is null.

fn unwrap(self) -> *mut N

Unwraps the wrapper type into the native pointer.

fn inner(&self) -> &N

Access the wrapped pointer.

fn inner_mut(&mut self) -> &mut N

Access the wrapped pointer.