impeller/
lib.rs

1//! impeller-rs: a tessellation-based 2D vector renderer.
2//!
3//! ```no_run
4//! use impeller::{BackendPreference, Canvas, Color, Context, Extent2D, Paint, PixelFormat, Rect};
5//!
6//! let mut ctx = Context::new(BackendPreference::Auto)?;
7//! let size = Extent2D::new(256, 256);
8//! let mut surface = ctx.create_surface(size, PixelFormat::Rgba8Unorm)?;
9//!
10//! let mut canvas = Canvas::new(size);
11//! canvas.clear(Color::WHITE);
12//! canvas.draw_rect(Rect::new(32.0, 32.0, 224.0, 224.0), &Paint::fill(Color::rgba8(0, 120, 220, 255)))?;
13//!
14//! ctx.draw(&mut surface, &canvas.finish())?;
15//! let pixels = ctx.read(&mut surface)?;
16//! ctx.destroy_surface(surface);
17//! # Ok::<(), impeller::Error>(())
18//! ```
19//!
20//! Which backend runs is decided when the context is created, not when the
21//! binary is built, so one image can boot on a board with a working Vulkan
22//! driver and on one where only GLES is usable.
23//!
24//! Code above the backend branches on [`Context::capabilities`] rather than on
25//! which backend it got. A device that cannot export a fence is the same
26//! problem whichever API it speaks, and asking which backend it is gets both
27//! cases wrong.
28
29pub mod backend;
30pub mod context;
31
32pub use backend::{Backend, BackendPreference};
33pub use context::{Context, Image, Surface};
34
35// The drawing API, so an application depends on this crate alone.
36pub use impeller_core::{
37    Affine2, Atlas, AtlasError, AtlasRect, BlendMode, Canvas, Color, ColorFilter, ColorForm,
38    ColorSpace, Coverage, Dash, Extent2D, FillRule, Gamma, GlyphKey, GradientStop, ImageFilter,
39    Layer, LineCap, LineJoin, MaskBlurStyle, Morphology, Paint, Path, PathBuilder, PixelFormat,
40    PointMode, PositionedGlyph, Recording, Rect, RoundingRadii, Sampling, Shader, SourceRect,
41    Sprite, StrokeStyle, Style, TileMode, Transform2D, Vec2, VertexMode, Vertices, MAX_STOPS,
42};
43pub use impeller_hal::{
44    mip_levels_for, BlendFactor, Capabilities, Error, Hal, Result, RuntimeProgram,
45    TextureDescriptor, TextureUsage, MORPHOLOGY_TAPS, RUNTIME_FLOATS,
46};
47
48/// Draw a recording into a texture this crate did not create.
49///
50/// [`Context::draw`] covers the case where the target came from
51/// [`Context::create_surface`], and that is the ordinary one. This is the other:
52/// a swapchain hands out its own images, and drawing into one means naming a
53/// texture the caller got from somewhere else. Without this the presentation
54/// path re-exported above reached a swapchain and then had nothing to draw into
55/// its images with, which is a window a caller can open and not fill.
56pub use impeller_core::{execute, execute_deferred, execute_layers, render_offscreen};
57
58/// Direct scanout to a display, with no compositor.
59#[cfg(feature = "drm")]
60pub use impeller_present_drm as drm;
61
62/// The Vulkan backend itself.
63///
64/// Re-exported because [`Context`] already exposes it: `Context::Vulkan` is a
65/// public variant holding a `VulkanContext`, so the type was part of this
66/// crate's surface whether or not it could be named. Without this a caller
67/// could match the variant and use what came out by inference, but could not
68/// write its type down -- so no function of theirs could take one, and reaching
69/// the swapchain meant depending on the backend crate separately and matching
70/// its version by hand.
71#[cfg(feature = "vulkan")]
72pub use impeller_hal_vulkan as vulkan;
73
74/// The GLES backend, re-exported for the same reason.
75#[cfg(feature = "gles")]
76pub use impeller_hal_gles as gles;
77
78/// A Vulkan WSI swapchain, for drawing into a window system's surface.
79///
80/// This was a feature name that enabled nothing for as long as it existed:
81/// `present-wsi` was in the default set and gated no dependency, and the crate
82/// implementing it was not one. So the facade's default build advertised a
83/// presentation path it had no route to, and a caller wanting a window had to
84/// reach past this crate to `impeller-present-vk` -- which the playground does,
85/// and which was the visible symptom nobody read as one.
86#[cfg(feature = "present-wsi")]
87pub use impeller_present_vk as wsi;
88
89/// An EGL window surface, which is the GLES backend's way to the same place.
90#[cfg(feature = "present-egl")]
91pub use impeller_present_egl as egl;
92
93/// Presentation targets and format negotiation.
94pub use impeller_present as present;
impeller/lib.rs

impeller/
lib.rs
