raden

name	raden
description	時雨堂の 2D ベクターグラフィックスライブラリ raden の使い方・API リファレンス。Cranelift JIT による CPU 専用ラスタライズ、Blend2D 互換 API (Context / Path / Gradient / Pattern / Font / Matrix2D)、29 種類の合成モード (Porter-Duff + ブレンド)、フィル・ストローク・Blit 描画、PixelFormat (Prgb32 / Xrgb32 / A8)、BMP 出力に関する質問時に使用。CI 環境で GPU を使わず 1080p 120fps のダミー映像を生成したい場面で参照。
license	Apache-2.0

Raden

時雨堂が開発する 2D ベクターグラフィックスライブラリ。Cranelift JIT を用いて CPU のみでラスタライズを行う。API は Blend2D にできるだけ寄せており、Blend2D 経験者がそのまま使い始められる。

目的と前提

• GPU が使えない CI 環境 (GitHub Actions など) で 1080p / 120fps 以上のダミー映像を生成する
• 対応プラットフォーム: Windows (x86_64) / macOS (arm64) / Ubuntu (x86_64 / arm64)
• 本格用途には Blend2D を推奨 (raden は実験的プロジェクト、API は予告なく変更される可能性がある)

依存関係

• cranelift-codegen / cranelift-frontend / cranelift-jit / cranelift-module / cranelift-native (~0.133)

公開型

// lib.rs の pub use
Context, Image, Matrix2D, Path, PathCmd, Point
Arc, Circle, Ellipse, Line, Rect, RoundRect, Triangle
Gradient, GradientStop, GradientValues, ExtendMode
LinearGradientValues, RadialGradientValues, ConicGradientValues
Pattern, PatternFilter
CompOp, FillRule, Rgba32, StrokeCap, StrokeJoin
Font, FontData, FontFace, FontError
PipelineRuntime, PixelFormat, premultiply_rgba

最小コード例

use raden::{Circle, CompOp, Context, Image, PipelineRuntime, PixelFormat, Rect, Rgba32};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut image = Image::new(320, 240, PixelFormat::Prgb32);
    let mut runtime = PipelineRuntime::new();
    let mut ctx = Context::new(&mut image, &mut runtime);

    ctx.set_comp_op(CompOp::SrcCopy);
    ctx.set_fill_style(Rgba32::rgb(0x20, 0x20, 0x60));
    ctx.fill_rect(&Rect::new(0.0, 0.0, 320.0, 240.0));

    ctx.set_comp_op(CompOp::SrcOver);
    ctx.set_fill_style(Rgba32::new(0xFF, 0x40, 0x40, 0xC0));
    ctx.fill_circle(&Circle::new(160.0, 120.0, 72.0));

    ctx.end();
    image.write_to_file("output.bmp")?;
    Ok(())
}

Context::new は &mut Image と &mut PipelineRuntime を借りる。PipelineRuntime は JIT コンパイル済みパイプラインのキャッシュを保持するため、フレームを跨いで再利用する。描画終了時は ctx.end() を呼ぶ。

描画 API

フィル描画 (Context)

メソッド	説明
fill_all()	現在のクリップ領域をフィルスタイルで塗りつぶす
fill_rect(&Rect)	矩形塗りつぶし (クリッピング付き)
fill_path(&Path)	任意パス塗りつぶし (ベジェ平坦化 + ラスタライズ)
fill_circle(&Circle)	円塗りつぶし
fill_ellipse(&Ellipse)	楕円塗りつぶし
fill_round_rect(&RoundRect)	角丸矩形塗りつぶし
fill_triangle(&Triangle)	三角形塗りつぶし
fill_polygon(&[Point])	ポリゴン塗りつぶし (3 点未満は no-op)
fill_pie(&Arc)	扇形塗りつぶし
fill_text(x, y, &Font, text)	テキスト描画 (全グリフを 1 つの Path に結合して fill_path)

ストローク描画 (Context)

メソッド	説明
stroke_line(&Line)	線分
stroke_rect(&Rect)	矩形
stroke_circle(&Circle)	円
stroke_ellipse(&Ellipse)	楕円
stroke_round_rect(&RoundRect)	角丸矩形
stroke_triangle(&Triangle)	三角形
stroke_polygon(&[Point])	ポリゴン (閉じる)
stroke_polyline(&[Point])	折れ線 (閉じない)
stroke_path(&Path)	任意パス (stroke-to-fill 変換後 fill_path)

クリア / Blit (Context)

メソッド	説明
clear_all()	現在のクリップ領域をピクセル値 0 で書き換える (comp_op は変更しない)
clear_rect(&Rect)	指定矩形をピクセル値 0 で書き換える (デバイス座標、変換行列は無視)
blit_image_at(x, y, &Image)	ソース画像全体を (x, y) に Nearest 転送
blit_image_rect(&Rect, &Image, Option<Rect>)	ソース矩形を宛先矩形に Nearest 転送。CompOp は SrcOver / SrcCopy のみ

変換 (Context)

後乗算 (matrix = matrix * T) は Blend2D / SVG / Canvas と互換。前乗算版 (post_*) も提供する。

メソッド	説明
translate(tx, ty)	平行移動 (後乗算)
scale(sx, sy)	スケーリング (後乗算)
rotate(angle)	回転 (ラジアン、後乗算)
rotate_around(angle, cx, cy)	指定中心まわりの回転 (後乗算)
skew(kx, ky)	せん断 (係数は接線、後乗算)
apply_matrix(&Matrix2D)	任意行列 (後乗算)
post_translate / post_scale / post_rotate / post_skew / post_transform	前乗算版
reset_matrix()	単位行列にリセット
user_to_meta()	Blend2D 互換エントリポイント (raden はユーザ行列をリセットするのみ)

状態管理 / クリッピング (Context)

メソッド	説明
save()	描画状態 (スタイル、変換、クリップ等) をスタックに保存
restore()	スタックから描画状態を復元
clip_to_rect(&Rect)	クリップ領域を指定矩形との積集合に縮小 (拡大不可)
restore_clipping()	クリップ領域を画像境界 (メタクリップ) に戻す

スタイル設定 (Context)

メソッド	説明
set_fill_style(Rgba32)	フィルを単色に
set_fill_style_gradient(&Gradient)	フィルをグラデーションに
set_fill_style_pattern(&Pattern)	フィルを画像パターンに
set_stroke_style(Rgba32)	ストロークを単色に
set_stroke_style_gradient(&Gradient)	ストロークをグラデーションに
set_stroke_style_pattern(&Pattern)	ストロークを画像パターンに
set_fill_rule(FillRule)	塗りつぶし規則 (NonZero / EvenOdd)
set_comp_op(CompOp)	合成モード
set_global_alpha(a)	全描画に乗算されるグローバルアルファ ([0, 1])
set_fill_alpha(a)	フィル個別アルファ ([0, 1])
set_stroke_alpha(a)	ストローク個別アルファ ([0, 1])

ストロークパラメータ

メソッド	説明
set_stroke_width(f64)	ストローク幅
set_stroke_cap(StrokeCap)	線端の形状 (Butt / Square / Round)
set_stroke_start_cap / set_stroke_end_cap	始端・終端を個別設定
set_stroke_join(StrokeJoin)	接合部の形状 (MiterClip / MiterBevel / MiterRound / Bevel / Round)
set_stroke_miter_limit(f64)	マイター限界値 (デフォルト 4.0)
set_stroke_dash_array(&[f64])	ダッシュパターン (SVG 準拠、奇数パターンは 2 回繰り返す)
set_stroke_dash_offset(f64)	ダッシュパターンの開始オフセット

グラデーション (Gradient)

種類	説明
Linear	2 点間の線形グラデーション
Radial	中心・焦点・半径による放射グラデーション
Conic	中心と角度による円錐グラデーション

範囲外処理 (ExtendMode): Pad (デフォルト) / Repeat / Reflect。

• fill_rect でグラデーションを塗ると set_comp_op の値を参照せず SrcOver 相当で合成する
• fill_path 経由では CompOp がパイプラインで適用される

パターン (Pattern)

画像をタイルとして繰り返す塗りつぶし。set_origin / set_transform、PatternFilter (Nearest / Bilinear)、ExtendMode (Pad / Repeat / Reflect) に対応。

• fill_rect でパターンを塗るときは set_comp_op が SrcOver または SrcCopy のみ対応 (それ以外はパニック)
• fill_path 経由では全 CompOp が適用できる

合成モード (CompOp)

Porter-Duff 基本セット + Clear + Plus の 13 種類とブレンド 16 種類の計 29 種類。

Porter-Duff 合成

モード	値	式
SrcOver	0	out = src + dst * (1 - srcA) (デフォルト)
SrcCopy	1	out = src
SrcIn	2	out = src * dstA
SrcOut	3	out = src * (1 - dstA)
SrcAtop	4	out = src * dstA + dst * (1 - srcA)
DstOver	5	out = dst + src * (1 - dstA)
DstCopy	6	out = dst
DstIn	7	out = dst * srcA
DstOut	8	out = dst * (1 - srcA)
DstAtop	9	out = dst * srcA + src * (1 - dstA)
Xor	10	out = src * (1 - dstA) + dst * (1 - srcA)
Clear	11	out = 0
Plus	12	out = min(src + dst, 1)

ブレンドモード

モード	値	説明
Minus	13	飽和減算。out = max(dst - src, 0)
Modulate	14	チャネル乗算。out = src * dst
Multiply	15	Multiply ブレンド
Screen	16	out = src + dst - src * dst
Overlay	17	暗部 Multiply、明部 Screen
Darken	18	min(src * dstA, dst * srcA)
Lighten	19	max(src * dstA, dst * srcA)
ColorDodge	20	覆い焼き (除算ベース)
ColorBurn	21	焼き込み (除算ベース)
LinearBurn	22	max(src + dst - srcA * dstA, 0)
LinearLight	23	LinearDodge + LinearBurn
PinLight	24	条件分岐 + min/max
HardLight	25	Overlay の src/dst 入替
SoftLight	26	除算 + sqrt
Difference	27	abs(src * dstA - dst * srcA)
Exclusion	28	out = src + dst - 2 * src * dst

塗りつぶし規則 (FillRule)

ルール	説明
NonZero	ワインディングナンバーが非ゼロなら内側 (デフォルト)
EvenOdd	ワインディングナンバーが奇数なら内側

フォント

型	説明
FontData	フォントファイルのバイトデータ。from_file(path) / from_bytes(bytes) で作成
FontFace	パース済みフォントフェイス。TrueType テーブル (head / hhea / hmtx / cmap / loca / glyf) を解析
Font	サイズ指定済みフォント。Font::from_face(&FontFace, size) を fill_text に渡す

パス (Path)

コマンド	説明
move_to(x, y)	サブパス開始点
line_to(x, y)	直線
quad_to(cpx, cpy, x, y)	2 次ベジェ
smooth_quad_to(x, y)	直前 quad_to の制御点を反射したスムーズ 2 次ベジェ
cubic_to(cp1x, cp1y, cp2x, cp2y, x, y)	3 次ベジェ
smooth_cubic_to(cp2x, cp2y, x, y)	直前 cubic_to の第 2 制御点を反射したスムーズ 3 次ベジェ
conic_to(cx, cy, ex, ey, w)	有理 2 次ベジェ (重み w > 0)
arc_to(cx, cy, rx, ry, start, sweep, force_move_to)	楕円弧 (cubic Bezier 近似)
close()	サブパスを閉じる
add_circle(cx, cy, r)	円を 4 本の cubic Bezier で近似 (Blend2D 互換 KAPPA)
add_ellipse(cx, cy, rx, ry)	楕円
add_round_rect(x, y, w, h, rx, ry)	角丸矩形 (rx / ry は幅・高さの半分でクランプ)
add_triangle(x0, y0, x1, y1, x2, y2)	三角形
add_polygon(&[Point])	閉じたポリゴン
add_polyline(&[Point])	折れ線 (閉じない)
add_pie(cx, cy, rx, ry, start, sweep)	扇形
translate(dx, dy) / transform(&Matrix2D)	全頂点を変換
add_path(&Path) / add_path_translated / add_path_transformed	別パスを取り込む
control_box() / bounding_box()	制御点ベースの bbox (曲線の厳密 bbox は未対応)

Image と PixelFormat

• Image::new(width, height, PixelFormat) で生成
• data() / data_mut() でバイト列参照
• write_to_file(path) で BI_BITFIELDS 形式 top-down BMP 出力

形式	説明
PixelFormat::Prgb32	32-bit premultiplied ARGB (デフォルト想定)
PixelFormat::Xrgb32	32-bit XRGB。アルファ未使用で Prgb32 と同一 JIT を共有
PixelFormat::A8	8-bit アルファ専用。単色 fill_rect とスカラ合成のみ対応

JIT パイプライン概要

• 29 種類全ての合成モードに対して完全カバレッジ版 + カバレッジ付き版を JIT 生成
• I32X4 (128-bit 整数 SIMD) による 4 ピクセル並列合成 (x86_64: SSE2 / AArch64: NEON)
• F32X4 による Radial グラデーションの 4 並列 sqrt
• Linear グラデーションの固定小数点最適化
• Linear fill_path は fetch + coverage + blend を融合 (中間バッファなし)
• sweep (prefix sum + FillRule 変換) を JIT 生成
• エッジ座標変換の F64X2 SIMD JIT
• PipelineRuntime がパイプラインキャッシュを保持し、同一パラメータは再コンパイルしない

現状の制約

• PixelFormat::A8: 単色 fill_rect とスカラ合成 (SrcOver / SrcCopy / Clear) のみ。fill_path / グラデ / パターンは未対応
• フォント: TrueType アウトライン (glyf / loca) のみ。CFF / OpenType Layout / カーニング / シェーピングは未対応
• クリッピング: 矩形のみ。パスクリッピングは未対応
• blit_image_*: Nearest 補間のみ、CompOp は SrcOver / SrcCopy のみ
• fill_rect + グラデ: CompOp を無視して SrcOver 相当で合成
• fill_rect + パターン: SrcOver / SrcCopy 以外はパニック
• 曲線パスの厳密なバウンディングボックスは未対応 (制御点ベース)

典型的な使い方

グラデーションで矩形を塗る

use raden::{CompOp, Context, Gradient, GradientStop, Image, PipelineRuntime, PixelFormat, Rect, Rgba32};

let mut image = Image::new(640, 480, PixelFormat::Prgb32);
let mut runtime = PipelineRuntime::new();
let mut ctx = Context::new(&mut image, &mut runtime);

let grad = Gradient::linear(0.0, 0.0, 640.0, 0.0)
    .add_stop(GradientStop::new(0.0, Rgba32::rgb(0xFF, 0x00, 0x00)))
    .add_stop(GradientStop::new(1.0, Rgba32::rgb(0x00, 0x00, 0xFF)));

ctx.set_comp_op(CompOp::SrcCopy);
ctx.set_fill_style_gradient(&grad);
ctx.fill_rect(&Rect::new(0.0, 0.0, 640.0, 480.0));
ctx.end();

パスをストロークする

use raden::{CompOp, Context, Image, Path, PipelineRuntime, PixelFormat, Rgba32, StrokeCap, StrokeJoin};

let mut image = Image::new(320, 240, PixelFormat::Prgb32);
let mut runtime = PipelineRuntime::new();
let mut ctx = Context::new(&mut image, &mut runtime);

let mut path = Path::new();
path.move_to(20.0, 120.0);
path.cubic_to(80.0, 20.0, 240.0, 220.0, 300.0, 120.0);

ctx.set_comp_op(CompOp::SrcOver);
ctx.set_stroke_style(Rgba32::rgb(0xFF, 0xFF, 0xFF));
ctx.set_stroke_width(4.0);
ctx.set_stroke_cap(StrokeCap::Round);
ctx.set_stroke_join(StrokeJoin::Round);
ctx.stroke_path(&path);
ctx.end();

状態の保存・復元でサブシーンを分離

ctx.save();
ctx.translate(100.0, 100.0);
ctx.rotate(std::f64::consts::FRAC_PI_4);
ctx.fill_rect(&Rect::new(-20.0, -20.0, 40.0, 40.0));
ctx.restore(); // 変換・スタイル・クリップを元に戻す

フレームを跨いで PipelineRuntime を使い回す

let mut image = Image::new(1920, 1080, PixelFormat::Prgb32);
let mut runtime = PipelineRuntime::new();

for frame in 0..120 {
    let mut ctx = Context::new(&mut image, &mut runtime);
    // 描画処理...
    ctx.end();
    // image.data() を表示・送信
}

PipelineRuntime を毎フレーム作り直すと JIT コンパイルが走り直すので性能が落ちる。フレームループの外側で 1 つだけ保持する。