6 releases (3 breaking)

✓ Uses Rust 2018 edition

0.17.0 Sep 9, 2019
0.16.0 Sep 1, 2019
0.15.0 Aug 18, 2019
0.14.4 Aug 10, 2019

#60 in Graphics APIs

Download history 46/week @ 2019-08-05 20/week @ 2019-08-12 26/week @ 2019-08-19 28/week @ 2019-08-26 43/week @ 2019-09-02

56 downloads per month
Used in 1 crate

MIT license

155KB
3.5K SLoC

C++ 2K SLoC // 0.1% comments Rust 1.5K SLoC // 0.1% comments

Safe Rust bindings to the Skia Graphics Library.

crates.io license Build Status

Skia Submodule Status: chrome/m77 (pending changes).

Goals

This project attempts to provide up to date safe bindings that bridge idiomatic Rust with Skia's C++ API on all major desktop, mobile, and WebAssembly platforms, including GPU rendering support for Vulkan, Metal, and OpenGL.

Status

Crate

Although we recommend to use the git repository because the prerelease on crates.io is a bit flaky at the moment, adding

[dependencies]
skia-safe = "0"

to your Cargo.toml should get you started.

Platforms & Build Targets

  • Windows
  • Linux Ubuntu 16 (18 should work, too).
  • macOS
  • Android (macOS | Linux -> aarch64, contributed by @DenisKolodin)
  • iOS
  • WebAssembly: #42 (help wanted).

Bindings & Supported Features

The supported bindings and Skia features are desribed in the skia-safe package's readme.

Building

Note that the information in this section is preliminary. Please open an issue for any build problem.

Prerequisites

This project requires LLVM, Python 2, and OpenSSL libraries to build.

To see which version of LLVM/Clang is available, use clang --version.

We recommend version 8, but also had successes to build Skia with 6.0.1 and 7.0.1, and - on macOS - Apple LLVM version 10. So it's probably best to use the preinstalled version or install version 8 if LLVM is not available on your platform by default.

Python version 2.7 must be available. The build script probes for python --version and python2 --version and uses the first one that looks like a version 2 executable.

OpenSSL libraries can be installed on Debian and Ubuntu with:

sudo apt-get install pkg-config libssl-dev

For other platforms, more information is available at the OpenSSL crate documentation.

macOS

  • Install the XCode command line developer tools with

    xcode-select --install
    
  • macOS Mojave Version 10.14: install the SDK headers:

    sudo open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg
    

    otherwise the Skia build may fail to build SkJpegUtility.cpp and the binding generation will fail with 'TargetConditionals.h' file not found . Also note that the command line developer tools and SDK headers should be reinstalled after an update of XCode.

  • As an alternative to Apple LLVM 10, install LLVM via brew install llvm or brew install llvm@7 and then set PATH, CPPFLAGS, and LDFLAGS like instructed.

Windows

  • Have the latest versions of git and Rust ready.

  • Install Visual Studio 2019 Build Tools or one of the other IDE releases. If you installed the IDE version, make sure that the Desktop Development with C++ workload is installed.

  • Install the latest LLVM 8 distribution.

  • MSYS2:

    • Install Python2 with pacman -S python2.
    • clang is always picked up from C:/Program Files/LLVM/bin, so be sure it's available from there.
  • Windows Shell (Cmd.exe):

    • Download and install Python version 2 from python.org.
  • Install and switch to the MSVC toolchain:

    rustup default stable-msvc
    

Linux

  • LLVM/Clang should be installed out of the box, if not, install version 8.

Then use:

cargo build -vv

On Linux, OpenGL libraries may be missing, if that is the case, install OpenGL drivers for you graphics card, or install a mesa OpenGL package like libgl1-mesa-dev.

Please share your build experience so that we can try to automate the build and get to the point where cargo build is sufficient to build the bindings including Skia, and if that is not possible, clearly prompts to what's missing.

Android

Cross compilation to Android is supported for targeting 64 bit ARM and Intel x86 architectures (aarch64 and x86_64) for API Level 26 (Oreo, Android 8):

For example, to compile for aarch64:

  1. Install the rust target:
    rustup target install aarch64-linux-android
    
  2. Download the r20 NDK for your host architecture and unzip it.
  3. Compile your package for the aarch64-linux-android target:

On macOS:

ANDROID_NDK=:path-to-android-ndk-r20 PATH=$PATH:$ANDROID_NDK/toolchains/llvm/prebuilt/darwin-x86_64/bin CC_aarch64_linux_android=aarch64-linux-android26-clang CXX_aarch64_linux_android=aarch64-linux-android26-clang++ CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER=aarch64-linux-android26-clang cargo build --target aarch64-linux-android -vv

On Linux:

ANDROID_NDK=:path-to-android-ndk-r20 PATH=$PATH:$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/bin CC_aarch64_linux_android=aarch64-linux-android26-clang CXX_aarch64_linux_android=aarch64-linux-android26-clang++ CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER=aarch64-linux-android26-clang cargo build --target aarch64-linux-android -vv

On Windows the Android NDK clang executable must be invoked through .cmd scripts:

ANDROID_NDK=:path-to-android-ndk-r20 PATH=$PATH:$ANDROID_NDK/toolchains/llvm/prebuilt/windows-x86_64/bin CC_aarch64_linux_android=aarch64-linux-android26-clang.cmd CXX_aarch64_linux_android=aarch64-linux-android26-clang++.cmd CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER=aarch64-linux-android26-clang.cmd cargo build --target aarch64-linux-android -vv

Notes:

  • The CARGO_TARGET_${TARGET}_LINKER environment variable name needs to be all uppercase.
  • In some older shells (for example macOS High Sierra), environment variable replacement can not be used when the variable was defined on the same line. Therefore the ANDROID_NDK variable must be defined before it's used in the PATH variable.
  • Rebuilding skia-bindings with a different target may cause linker errors, in that case touch skia-bindings/build.rs will force a rebuild (#10).

iOS

Compilation to iOS is supported on macOS targeting the iOS simulator (--target x86_64-apple-ios) and 64 bit ARM devices (--target aarch64-apple-ios).

Skia

For situations in which Skia does not build or needs to be configured differently, we support some customization support in skia-bindings/build.rs. For more details about how to customize Skia builds, take a look at the README of the skia-bindings package.

Note that crate packages will try to download prebuilt binaries from skia-binaries if the platform matches with one of the binaries build on the CI. If the download fails, a full build of Skia is triggered.

Examples

The examples are taken from Skia's website and ported to the Rust API.

If you were able to build the project, run

cargo run --example skia-org -- [OUTPUT_DIR]

to generate some Skia drawn PNG images in the directory OUTPUT_DIR. To render with OpenGL, use

cargo run --example skia-org -- [OUTPUT_DIR] --driver opengl

And to show the drivers that are supported

cargo run --example skia-org -- --help

Some examples:

Fill, Stroke, Text:

Fill, Stroke, Text

Sweep Gradient:

Sweep Gradient

Dash Path Effect:

Dash Path Effect

For more, you may take a look at the rust-skia.github.io repository.

This project needs contributions!

If you'd like to help with the bindings, take a look at the Wiki to get started and create an issue to avoid duplicate work. For smaller tasks, grep for "TODO" in the source code. And for heroic work, check out the label help wanted. And if you like to help making the Rust API nicer to use, look out for open issues with the label api ergonomics.

Maintainers

License

MIT

  

Dependencies

~0–2.7MB
~56K SLoC