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

pub struct Surface(/* private fields */);

Implementations

impl Surface

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

👎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: &ImageInfo, row_bytes: impl Into<Option<usize>>, surface_props: Option<&SurfaceProps>, ) -> Option<Self>

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

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

pub fn from_backend_texture( context: &mut RecordingContext, backend_texture: &BackendTexture, origin: SurfaceOrigin, sample_cnt: impl Into<Option<usize>>, color_type: ColorType, color_space: impl Into<Option<ColorSpace>>, surface_props: Option<&SurfaceProps>, ) -> Option<Self>

👎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 RecordingContext, backend_render_target: &BackendRenderTarget, origin: SurfaceOrigin, color_type: ColorType, color_space: impl Into<Option<ColorSpace>>, surface_props: Option<&SurfaceProps>, ) -> Option<Self>

👎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 RecordingContext, budgeted: Budgeted, image_info: &ImageInfo, sample_count: impl Into<Option<usize>>, surface_origin: impl Into<Option<SurfaceOrigin>>, surface_props: Option<&SurfaceProps>, should_create_with_mips: impl Into<Option<bool>>, ) -> Option<Self>

👎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

pub unsafe fn from_ca_metal_layer( context: &mut RecordingContext, layer: Handle, origin: SurfaceOrigin, sample_cnt: impl Into<Option<usize>>, color_type: ColorType, color_space: impl Into<Option<ColorSpace>>, surface_props: Option<&SurfaceProps>, drawable: *mut Handle, ) -> Option<Self>

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

Creates Surface from CAMetalLayer. Returned Surface takes a reference on the CAMetalLayer. The ref on the layer will be released when the Surface is destroyed.

Only available when Metal API is enabled.

Will grab the current drawable from the layer and use its texture as a backend_rt to create a renderable surface.

• context - GPU context
• layer - gpu::mtl::Handle (expected to be a CAMetalLayer*)
• 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
• drawable - Pointer to drawable to be filled in when this surface is instantiated; may not be None

Returns: created Surface, or None

pub unsafe fn from_mtk_view( context: &mut RecordingContext, mtk_view: Handle, origin: SurfaceOrigin, sample_count: impl Into<Option<usize>>, color_type: ColorType, color_space: impl Into<Option<ColorSpace>>, surface_props: Option<&SurfaceProps>, ) -> Option<Self>

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

Creates Surface from MTKView. Returned Surface takes a reference on the MTKView. The ref on the layer will be released when the Surface is destroyed.

Only available when Metal API is enabled.

Will grab the current drawable from the layer and use its texture as a backend_rt to create a renderable surface.

• context - GPU context
• layer - gpu::mtl::Handle (expected to be a MTKView*)
• 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: created Surface, or None

impl Surface

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

👎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(&self) -> ImageInfo

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: ContentChangeMode, ) -> &mut Self

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 Surface

pub fn recording_context(&self) -> Option<RecordingContext>

Returns the recording context being used by the Surface.

Returns: the recording context, if available; None otherwise

pub fn direct_context(&self) -> Option<DirectContext>

rust-skia helper, not in Skia

pub fn get_backend_texture( &mut self, handle_access: BackendHandleAccess, ) -> Option<BackendTexture>

👎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: BackendHandleAccess, ) -> Option<BackendRenderTarget>

👎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: &BackendTexture, origin: SurfaceOrigin, ) -> 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: &BackendTexture, origin: SurfaceOrigin, mode: impl Into<Option<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 Surface

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: &ImageInfo) -> Option<Self>

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

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

pub fn image_snapshot(&mut self) -> Image

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 make_temporary_image(&mut self) -> Option<Image>

Returns an Image capturing the current Surface contents. However, the contents of the Image are only valid as long as no other writes to the Surface occur. If writes to the original Surface happen then contents of the Image are undefined. However, continued use of the Image should not cause crashes or similar fatal behavior.

This API is useful for cases where the client either immediately destroys the Surface after the Image is created or knows they will destroy the Image before writing to the Surface again.

This API can be more performant than Self::image_snapshot() as it never does an internal copy of the data assuming the user frees either the Image or Surface as described above.

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

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<&Paint>, )

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 Ganesh GPU backend. Graphite has deprecated this API in favor of the equivalent asynchronous API on skgpu::graphite::Context (with an optional explicit synchonization).

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: &ImageInfo, 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 Ganesh GPU backend. Graphite has deprecated this API in favor of the equivalent asynchronous API on skgpu::graphite::Context (with an optional explicit synchonization).

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: &Bitmap, 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 Ganesh GPU backend. Graphite has deprecated this API in favor of the equivalent asynchronous API on skgpu::graphite::Context (with an optional explicit synchonization).

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: &Bitmap, 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 Surface

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 Debug for Surface

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

Formats the value using the given formatter.