Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
skulpin
Skia + Vulkan = Skulpin
This crate provides an easy option for drawing hardware-accelerated 2D by combining vulkan and skia. (And a dash of winit!)
This crate mainly depends on:
- ash - Vulkan bindings for Rust
- skia-safe - Skia bindings for Rust
- winit - Cross-platform window handling
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.
Usage
Currently there are two ways to use this library.
- app - Implement the AppHandler trait and launch the app. It's simple but not as flexible.
- renderer_only - You manage the window and event loop yourself. Then add the renderer to draw to it.
Don't forget to install the prerequisites below appropriate to your platform! (See "Requirements")
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.
cargo run --example interactive
The physics demo is fun too.
cargo run --example physics
Here's a video of the physics and interactive examples.
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.36.0
Windows
All examples require the LunarG Validation layers and a Vulkan library that is visible in your PATH
. An easy way to
get started is to use the LunarG Vulkan SDK
MacOS
All examples require the LunarG Validation layers and a Vulkan library that is visible in your PATH
. An easy way to
get started is to use the LunarG Vulkan SDK
Linux
All examples require the LunarG Validation layers and a Vulkan library that is visible in your PATH
. An easy way to
get started is to use the LunarG Vulkan SDK
On linux you'll also need to link against bz2, GL, fontconfig, and freetype.
On ubuntu, you could use libbz2-dev
, libfreetype6-dev
, libfontconfig1-dev
, and libgl-dev
. (And libvulkan-dev
to pick up the Vulkan SDK)
Other Platforms
It may be possible to build this for mobile platforms, but I've not investigated this yet.
Status
For now this is a proof-of-concept. I think there is desire for a simple entry point to drawing on the screen, and that this approach can provide a good balance of performance, features, and ease-of-use for many applications.
Flutter, Google's new UI framework, uses a Skia + Vulkan stack to achieve 60+ FPS on mobile devices. So I expect this type of usage to be maintained and improved as needed in the upstream libraries.
A note on High-DPI Display Support
For the common case, you can draw to the skia canvas using winit's "logical" coordinates and not worry about dpi/scaling issues.
Internally, the skia surface will match the swapchain size, but this size is not necessarily winit's 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 two main choices you should consider when configuring how your app runs
- Presentation Mode - You'll likely either want Fifo (default) or Mailbox
Fifo
(VK_PRESENT_MODE_FIFO_KHR
) is the default behavior and is always present on devices that fully comply to spec. This will be VSync,shouldn't ever screen tear, and will generally run at display refresh rate.Mailbox
(VK_PRESENT_MODE_MAILBOX_KHR
) will render as quickly as possible. The frames are queued and the latest complete frame will be drawn. Other frames will be dropped. This rendering method will produce the lowest latency, but is not always available, and could be an unnecessary drain on battery life for laptops and mobile devices.- See
prefer_fifo_present_mode
/prefer_mailbox_present_mode
for a simple way to choose between the two recommended options orpresent_mode_priority
for full control. - For full details see documentation for
PresentMode
and the Vulkan spec.
- Device Type - The most common device types will be Dedicated or Integrated. By default, a Dedicated device is chosen
when available.
Discrete
(VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
) - When available, this is likely to be the device with best performanceIntegrated
(VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU
) - This will generally be more power efficient that a Discrete GPU.- I suspect the most likely case of having both would be a laptop with a discrete GPU. I would expect that favoring the integrated GPU would be better for battery life, at the cost of some performance. However I don't have a suitable device to test this.
- See
prefer_integrated_gpu
/prefer_discrete_gpu
for a simple way to choose between the two recommended options orphysical_device_type_priority
for full control - For full details see documentation for
PhysicalDeviceType
and the Vulkan spec.
- Vulkan Debug Layer - Debug logging is fully enabled by default
use_vulkan_debug_layer
turns all logging on/offvalidation_layer_debug_report_flags
allows choosing specific log levels- If the Vulkan SDK is not installed, the app will fail to start if any vulkan debugging is enabled
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
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.