Skia Ruby

Skia bindings for Ruby, providing 2D drawing, image processing, PDF generation, runtime shaders, skottie animation, and SVG path/DOM rendering.

This project provides a practical, SkiaSharp-compatible API surface in Ruby, with a mix of:

• native-backed features through SkiaSharp C API
• Ruby convenience/typed layers for ergonomic usage

• Surface / Canvas / Paint / Path / Image / Shader
• Shape and path drawing (rect, rrect, arc, points, picture playback)
• Document PDF output
  • file output
  • memory stream output
  • metadata (title, author, creation, pdfa, etc.)
• Picture recording / playback / serialization
• RuntimeEffect (SkSL compile and shader creation)
• Skottie (Lottie JSON animation load/seek/render)
• Encoders (PNG, JPEG, WEBP)

• Geometry/value types
  • Point, Rect, RRect, Matrix, ImageInfo, ColorSpace
• Effect wrappers
  • MaskFilter, ColorFilter, ImageFilter, PathEffect
• Pixel APIs
  • Bitmap, Pixmap, read_pixels helpers
• Text primitives
  • Font, Typeface, TextBlob
• Structured helpers
  • Textlayout (Shaper, Paragraph)
  • Svg::Dom (<path> load and draw)

• Text layout modules (skunicode, skshaper, skparagraph) are generally not exposed in libSkiaSharp builds.
• This gem checks symbol availability at runtime and raises UnsupportedOperationError with the missing symbol names.

• Ruby 3.0+
• SkiaSharp native library (libSkiaSharp)
  • macOS: libSkiaSharp.dylib
  • Linux: libSkiaSharp.so
  • Windows: libSkiaSharp.dll

Add this line to your application's Gemfile:

gem 'skia'

Then run:

bundle install

The gem loads libSkiaSharp from project root, current working directory, SKIA_LIBRARY_PATH, or system path.

Use the bundled installer scripts (defaults to prebuilt download):

scripts/install_native_skia.sh prebuilt
export SKIA_NATIVE_SOURCE=prebuilt
export SKIA_PREBUILT_DIR="$PWD/vendor/native/$(uname | tr '[:upper:]' '[:lower:]')"

On Windows:

.\scripts\install_native_skia.ps1 -Mode prebuilt
$env:SKIA_NATIVE_SOURCE = "prebuilt"
$env:SKIA_PREBUILT_DIR = "$pwd\\vendor\\native\\windows"

SKIA_NATIVE_SOURCE modes:

• auto: explicit path / local / prebuilt / system fallback
• local: use local library only (SKIA_LIBRARY_PATH required)
• prebuilt: use prebuilt vendor path (SKIA_PREBUILT_DIR or vendor/native/<platform>)

curl -L -o skiasharp.nupkg \
  https://api.nuget.org/v3-flatcontainer/skiasharp.nativeassets.macos/3.119.2/skiasharp.nativeassets.macos.3.119.2.nupkg
unzip skiasharp.nupkg -d skiasharp-extract
cp skiasharp-extract/runtimes/osx/native/libSkiaSharp.dylib .

curl -L -o skiasharp.nupkg https://www.nuget.org/api/v2/package/SkiaSharp.NativeAssets.Linux.x64
unzip skiasharp.nupkg -d skiasharp-extract
cp skiasharp-extract/runtimes/linux-x64/native/libSkiaSharp.so .

Invoke-WebRequest -Uri https://www.nuget.org/api/v2/package/SkiaSharp.NativeAssets.Win32 -OutFile skiasharp.nupkg
Expand-Archive skiasharp.nupkg -DestinationPath skiasharp-extract
copy skiasharp-extract\runtimes\win-x64\native\libSkiaSharp.dll .

require 'skia'

surface = Skia::Surface.make_raster(640, 480)

surface.draw do |canvas|
  canvas.clear(Skia::Color::WHITE)

  paint = Skia::Paint.new
  paint.antialias = true
  paint.color = Skia::Color::RED

  canvas.draw_circle(320, 240, 100, paint)
end

surface.save_png('output.png')

require 'skia'

Skia::Document.create_pdf('output.pdf', metadata: {
  title: 'My Report',
  author: 'skia-ruby',
  creation: Time.now,
  raster_dpi: 144.0,
  encoding_quality: 90
}) do |doc|
  doc.page(612, 792) do |canvas|
    canvas.clear(Skia::Color::WHITE)

    font = Skia::Font.new(nil, 24.0)
    paint = Skia::Paint.new
    paint.color = Skia::Color::BLACK

    canvas.draw_text('Hello, PDF!', 50, 100, font, paint)
  end
end

require 'skia'

sksl = <<~SKSL
  half4 main(float2 coord) {
    half r = coord.x / 640.0;
    half g = coord.y / 360.0;
    return half4(r, g, 0.35, 1.0);
  }
SKSL

effect = Skia::RuntimeEffect.make_for_shader(sksl)
shader = effect.make_shader

surface = Skia::Surface.make_raster(640, 360)
paint = Skia::Paint.new
paint.shader = shader

surface.draw do |canvas|
  canvas.draw_rect(Skia::Rect.from_wh(640, 360), paint)
end

surface.save_png('runtime_effect.png')

After checking out the repo, install dependencies:

bundle install

Run examples:

ruby examples/basic_drawing.rb
ruby examples/gradient.rb
ruby examples/bar_chart.rb
ruby examples/advanced_features.rb
ruby examples/pdf_stream.rb
ruby examples/runtime_effect.rb
ruby examples/textlayout.rb
ruby examples/skottie.rb
ruby examples/svg_dom.rb

Release and upstream sync guidance: docs/release-checklist.md

This project is available under the MIT License.

Bug reports and pull requests are welcome at:

• https://github.com/ydah/skia-ruby