vello_gpu/README.md - external/github.com/linebender/vello - Git at Google


            
            <div align="center">


            # Vello GPU


            **GPU renderer with CPU-side preprocessing**


            [![Apache 2.0 or MIT license.](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue.svg)](#license)

            
            \

            
            [![Linebender Zulip chat.](https://img.shields.io/badge/Linebender-%23vello-blue?logo=Zulip)](https://xi.zulipchat.com/#narrow/channel/197075-vello) [![GitHub Actions CI status.](https://img.shields.io/github/actions/workflow/status/linebender/vello/ci.yml?logo=github&label=CI)](https://github.com/linebender/vello/actions)


            </div>


            <!-- We use cargo-rdme to update the README with the contents of lib.rs.

            
            To edit the following section, update it in lib.rs, then run:

            
            cargo rdme --workspace-project=vello_gpu

            
            Full documentation at https://github.com/orium/cargo-rdme -->


            <!-- Intra-doc links used in lib.rs should be evaluated here.

            
            See https://linebender.org/blog/doc-include/ for related discussion. -->


            [`Resources`]: https://docs.rs/vello_gpu/latest/vello_gpu/struct.Resources.html

            
            [`Scene::glyph_run`]:

            
              https://docs.rs/vello_gpu/latest/vello_gpu/struct.Scene.html#method.glyph_run


            <!-- cargo-rdme start -->


            A GPU renderer for 2D vector graphics with CPU-side preprocessing.


            Vello GPU uses the Sparse Strips architecture to divide work between CPU

            
            preprocessing and GPU rendering:


            - The CPU processes paths, tiles, and schedules sparse strips.

            
            - The GPU rasterizes those strips and performs compositing.

            
            - The compact strip representation limits data transfer between them.


            ### Key Features


            - Efficient path rendering with CPU-side processing

            
            - GPU-accelerated compositing and blending

            
            - Support for both windowed and headless rendering


            ### Feature Flags


            - `wgpu` (enabled by default): Enables the GPU rendering backend via wgpu and

            
              includes the required Vello GPU shaders.

            
            - `wgpu_default` (enabled by default): Enables wgpu with its default hardware

            
              backends (such as Vulkan, Metal, and DX12).

            
            - `text` (enabled by default): Enables glyph rendering ([`Scene::glyph_run`]).

            
            - `all_shader_features` (enabled by default): Enables all optional shader

            
              features.

            
            - `blurred_rounded_rect` (enabled by default): Enables rendering of blurred

            
              rounded rectangles.

            
            - `full_image_support` (enabled by default): If this feature is disabled, only

            
              external textures using `TextureRegion::Full` with nearest or bilinear

            
              sampling and opacity are supported. Enabling this feature also adds support

            
              for uploaded images, glyph atlas caching, bicubic sampling, cropped external

            
              textures, and colored or alpha-mask tints.

            
            - `gradient_sweep` (enabled by default): Enables rendering of sweep gradients

            
            - `wgpu_external_texture` (enabled by default): Adds a WGSL `texture_external`

            
              binding when the wgpu device has `wgpu::Features::EXTERNAL_TEXTURE` enabled,

            
              so `wgpu::ExternalTexture`s (e.g. multi-planar YCbCr video frames) can be

            
              bound with `TextureBindings::insert_wgpu_external_texture`. Other images are

            
              not affected.

            
            - `webgl`: Enables the WebGL rendering backend for browser support, using GLSL

            
              shaders for compatibility.


            If you need to customize the set of enabled wgpu features, disable this crate's

            
            default features then enable its `wgpu` feature. You can then depend on wgpu

            
            directly, setting the specific features you require. Don't forget to also

            
            disable wgpu's default features.


            ### Architecture


            The renderer is split into several key components:


            - `Scene`: Manages the render context and path processing on the CPU

            
            - `Renderer` or `WebGlRenderer`: Handles GPU resource management and executes

            
              draw operations


            See the individual module documentation for more details on usage and

            
            implementation.


            ### Current state


            Vello GPU is a solid GPU-accelerated 2D renderer with broad, reliable feature

            
            support. Although it does not match the compute-centric `vello` renderer's raw

            
            performance on dynamic and vector-heavy workloads, it provides excellent

            
            performance on workloads that benefit from GPU acceleration, such as images,

            
            gradients, and filters. Overall, we still consider it to be slightly less mature

            
            than its CPU-only counterpart Vello CPU.


            Vello GPU remains under active development. Known limitations include:


            - The following features are not yet supported and will panic: Mask layers,

            
              complex filter graphs as well as certain blend modes for non-isolated

            
              blending.

            
            - Parts of the API and its documentation are still suboptimal, for example the

            
              lifecycle and ownership of external resources through [`Resources`][].

            
            - Some exposed features remain experimental and are not recommended for use,

            
              including glyph caching. Experimental APIs are identified in their method

            
              documentation.

            
            - Parts of the rendering pipeline are not yet fully optimized, particularly the

            
              wgpu backend, but also other aspects.

            
            - Some failures panic instead of being reported through a user-facing error.


            With that said, we are continuously improving Vello GPU and will address these

            
            and other limitations in future releases.


            ### Package rename


            This package was previously named `vello_hybrid`. New dependencies and Rust

            
            imports should use `vello_gpu`; no compatibility re-export package is provided

            
            in this repository. Existing crates.io releases under `vello_hybrid` remain

            
            available, and publication under the new name may lag behind the repository

            
            rename.


            <!-- cargo-rdme end -->


            ## Minimum supported Rust Version (MSRV)


            This version of Vello GPU has been verified to compile with **Rust 1.89** and

            
            later.


            Future versions of Vello GPU might increase the Rust version requirement. It

            
            will not be treated as a breaking change and as such can even happen with small

            
            patch releases.


            <details>

            
            <summary>Click here if compiling fails.</summary>


            As time has passed, some of Vello GPU's dependencies could have released

            
            versions with a higher Rust requirement. If you encounter a compilation issue

            
            due to a dependency and don't want to upgrade your Rust toolchain, then you

            
            could downgrade the dependency.


            ```sh

            
            # Use the problematic dependency's name and version

            
            cargo update -p package_name --precise 0.1.1

            
            ```


            </details>


            ## Community


            Discussion of Vello GPU development happens in the

            
            [Linebender Zulip](https://xi.zulipchat.com/), specifically the

            
            [#vello channel](https://xi.zulipchat.com/#narrow/channel/197075-vello). All

            
            public content can be read without logging in.


            Contributions are welcome by pull request. The [Rust code of conduct] applies.


            ## License


            Licensed under either of


            - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or

            
              <http://www.apache.org/licenses/LICENSE-2.0>)

            
            - MIT license ([LICENSE-MIT](LICENSE-MIT) or

            
              <http://opensource.org/licenses/MIT>)


            at your option.


            [Rust code of conduct]: https://www.rust-lang.org/policies/code-of-conduct
	<div align="center">

	# Vello GPU

	GPU renderer with CPU-side preprocessing

	[![Apache 2.0 or MIT license.](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue.svg)](#license)
	\
	[![Linebender Zulip chat.](https://img.shields.io/badge/Linebender-%23vello-blue?logo=Zulip)](https://xi.zulipchat.com/#narrow/channel/197075-vello) [![GitHub Actions CI status.](https://img.shields.io/github/actions/workflow/status/linebender/vello/ci.yml?logo=github&label=CI)](https://github.com/linebender/vello/actions)

	</div>

	<!-- We use cargo-rdme to update the README with the contents of lib.rs.
	To edit the following section, update it in lib.rs, then run:
	cargo rdme --workspace-project=vello_gpu
	Full documentation at https://github.com/orium/cargo-rdme -->

	<!-- Intra-doc links used in lib.rs should be evaluated here.
	See https://linebender.org/blog/doc-include/ for related discussion. -->

	[`Resources`]: https://docs.rs/vello_gpu/latest/vello_gpu/struct.Resources.html
	[`Scene::glyph_run`]:
	https://docs.rs/vello_gpu/latest/vello_gpu/struct.Scene.html#method.glyph_run

	<!-- cargo-rdme start -->

	A GPU renderer for 2D vector graphics with CPU-side preprocessing.

	Vello GPU uses the Sparse Strips architecture to divide work between CPU
	preprocessing and GPU rendering:

	- The CPU processes paths, tiles, and schedules sparse strips.
	- The GPU rasterizes those strips and performs compositing.
	- The compact strip representation limits data transfer between them.

	### Key Features

	- Efficient path rendering with CPU-side processing
	- GPU-accelerated compositing and blending
	- Support for both windowed and headless rendering

	### Feature Flags

	- `wgpu` (enabled by default): Enables the GPU rendering backend via wgpu and
	includes the required Vello GPU shaders.
	- `wgpu_default` (enabled by default): Enables wgpu with its default hardware
	backends (such as Vulkan, Metal, and DX12).
	- `text` (enabled by default): Enables glyph rendering ([`Scene::glyph_run`]).
	- `all_shader_features` (enabled by default): Enables all optional shader
	features.
	- `blurred_rounded_rect` (enabled by default): Enables rendering of blurred
	rounded rectangles.
	- `full_image_support` (enabled by default): If this feature is disabled, only
	external textures using `TextureRegion::Full` with nearest or bilinear
	sampling and opacity are supported. Enabling this feature also adds support
	for uploaded images, glyph atlas caching, bicubic sampling, cropped external
	textures, and colored or alpha-mask tints.
	- `gradient_sweep` (enabled by default): Enables rendering of sweep gradients
	- `wgpu_external_texture` (enabled by default): Adds a WGSL `texture_external`
	binding when the wgpu device has `wgpu::Features::EXTERNAL_TEXTURE` enabled,
	so `wgpu::ExternalTexture`s (e.g. multi-planar YCbCr video frames) can be
	bound with `TextureBindings::insert_wgpu_external_texture`. Other images are
	not affected.
	- `webgl`: Enables the WebGL rendering backend for browser support, using GLSL
	shaders for compatibility.

	If you need to customize the set of enabled wgpu features, disable this crate's
	default features then enable its `wgpu` feature. You can then depend on wgpu
	directly, setting the specific features you require. Don't forget to also
	disable wgpu's default features.

	### Architecture

	The renderer is split into several key components:

	- `Scene`: Manages the render context and path processing on the CPU
	- `Renderer` or `WebGlRenderer`: Handles GPU resource management and executes
	draw operations

	See the individual module documentation for more details on usage and
	implementation.

	### Current state

	Vello GPU is a solid GPU-accelerated 2D renderer with broad, reliable feature
	support. Although it does not match the compute-centric `vello` renderer's raw
	performance on dynamic and vector-heavy workloads, it provides excellent
	performance on workloads that benefit from GPU acceleration, such as images,
	gradients, and filters. Overall, we still consider it to be slightly less mature
	than its CPU-only counterpart Vello CPU.

	Vello GPU remains under active development. Known limitations include:

	- The following features are not yet supported and will panic: Mask layers,
	complex filter graphs as well as certain blend modes for non-isolated
	blending.
	- Parts of the API and its documentation are still suboptimal, for example the
	lifecycle and ownership of external resources through [`Resources`][].
	- Some exposed features remain experimental and are not recommended for use,
	including glyph caching. Experimental APIs are identified in their method
	documentation.
	- Parts of the rendering pipeline are not yet fully optimized, particularly the
	wgpu backend, but also other aspects.
	- Some failures panic instead of being reported through a user-facing error.

	With that said, we are continuously improving Vello GPU and will address these
	and other limitations in future releases.

	### Package rename

	This package was previously named `vello_hybrid`. New dependencies and Rust
	imports should use `vello_gpu`; no compatibility re-export package is provided
	in this repository. Existing crates.io releases under `vello_hybrid` remain
	available, and publication under the new name may lag behind the repository
	rename.

	<!-- cargo-rdme end -->

	## Minimum supported Rust Version (MSRV)

	This version of Vello GPU has been verified to compile with Rust 1.89 and
	later.

	Future versions of Vello GPU might increase the Rust version requirement. It
	will not be treated as a breaking change and as such can even happen with small
	patch releases.

	<details>
	<summary>Click here if compiling fails.</summary>

	As time has passed, some of Vello GPU's dependencies could have released
	versions with a higher Rust requirement. If you encounter a compilation issue
	due to a dependency and don't want to upgrade your Rust toolchain, then you
	could downgrade the dependency.

	```sh
	# Use the problematic dependency's name and version
	cargo update -p package_name --precise 0.1.1
	```

	</details>

	## Community

	Discussion of Vello GPU development happens in the
	[Linebender Zulip](https://xi.zulipchat.com/), specifically the
	[#vello channel](https://xi.zulipchat.com/#narrow/channel/197075-vello). All
	public content can be read without logging in.

	Contributions are welcome by pull request. The [Rust code of conduct] applies.

	## License

	Licensed under either of

	- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
	<http://www.apache.org/licenses/LICENSE-2.0>)
	- MIT license ([LICENSE-MIT](LICENSE-MIT) or
	<http://opensource.org/licenses/MIT>)

	at your option.

	[Rust code of conduct]: https://www.rust-lang.org/policies/code-of-conduct