search

aclysma / skulpin

Skia + Vulkan = Skulpin
Apache License 2.0
399 stars 41 forks source link

readme

skulpin

Skia + Vulkan = Skulpin

This crate provides an easy option for drawing hardware-accelerated 2D by combining vulkan and skia.

Please note the status of this crate before using.

Build Status Crates.io

Example Screenshot

This crate mainly depends on:

NOTE: See skia-bindings for more info on how a skia binary acquired. In many cases, this crate will download a binary created by their project's CI.

This crate integrates with raw-window-handle, which allows it to be used with sdl2, winit, and any other windowing framework that supports raw-window-handle.

Running the Examples

First, ensure that the below requirements are met depending on OS. Afterwards, the examples can be run normally.

The interactive example is good to look at for an easy way to get keyboard/mouse input.

# winit 0.24
cargo run --example interactive_winit_app --features winit-app,winit-25

# sdl2
cargo run --example interactive_sdl2

The physics demo is fun too.

cargo run --example physics --features winit-app,winit-25

Here's a video of the physics and interactive examples.

IMAGE ALT TEXT

Status

I am no longer using this crate for anything, so will only maintain this crate on a very minimal basis. I will review simple pull requests and offer suggestions on opened issues. However, I may fully sunset this repo at any time, particularly if the crate stops working and requires more than trivial changes to fix. Unfortunately, I have limited time to work on open source, so I want to focus it on crates that I think are most interesting to me personally. I'm open to passing ownership of the crate to someone who has made a few PRs and shown themselves to be trustworthy, and will be glad to link to a fork if someone makes one.

Usage

Currently there are two ways to use this library with winit.

If you prefer sdl2 you'll need to use the renderer directly. See sdl2 renderer only

Don't forget to install the prerequisites below appropriate to your platform! (See "Requirements")

Feature Flags

Skia-related features:

The skia-bindings prebuilt binaries are only available for certain combinations of features. As of this writing, it is available for none, each feature individually, or all features enabled. The vulkan feature is required and implicitly used, so enabling any features individually will substantially increase build times. It's recommended to use all features (default behavior), or disable all features. (use default-features = false)

Skulpin features:

If using winit-app, you MUST specify a winit version feature flag (see below)

Winit version feature flags:

(These feature names match the imgui-rs crate.)

Examples of Feature Flag Usage

# Pull in all skia features and support for all backends (sdl2 and winit)
skulpin = "0"

# Pull in all skia features but not the winit app wrapper
skulpin = { version = "0", default-features = false, features = ["skia-complete"] }

# Pull in all skia features and include the winit app wrapper
skulpin = { version = "0", default-features = false, features = ["skia-complete", "winit-app"] }

Upstream Versioning of skia-safe

Skulpin can be built and used with many versions of skia-safe. In order to be accomodating to users of the library, the required version has been left open-ended. This allows new projects to use more recent versions of these libraries while not forcing old projects to update.

You can force a particular version of skia safe by using cargo update

cargo update -p skia-safe --precise 0.32

Documentation

Documentation fails to build on docs.rs because the skia_safe crate requires an internet connection to build. (It will either grab skia source code, or grab a prebuilt binary.) So the best way to view docs is to build them yourself:

cargo doc -p skulpin --open

Requirements

Minimum required rust version: 1.43.0

Windows

MacOS

Linux

Other Platforms

It may be possible to build this for mobile platforms, but I've not investigated this yet.

A note on High-DPI Display Support

For the common case, you can draw to the skia canvas using "logical" coordinates and not worry about dpi/scaling issues.

Internally, the skia surface will match the swapchain size, but this size is not necessarily LogicalSize or PhysicalSize of the window. In order to produce consistently-sized results, the renderer will apply a scaling factor to the skia canvas before handing it off to your draw implementation.

Important configuration choices

There are a few primary choices you should consider when configuring how your app runs

License

Licensed under either of

at your option.

The fonts directory contains several fonts under their own licenses:

sdl2 uses the zlib license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See LICENSE-APACHE and LICENSE-MIT.