visual

موتور رسم دوبعدی به سبک PixiJS. از شکل‌ها یک گراف صحنه بساز و آن را با یکی از سه پشتوانه (Canvas2D، WebGL یا WebGPU) که در زمان اجرا برگزیده می‌شود رسم کن.

موتور لایه‌لایه است: Application (چرخهٔ عمر و حلقهٔ رسم)، زیر آن Renderer (همان پشتوانه)، و سپس گراف صحنه‌ای که از Container (یک گروه) تا Graphics (چیزی که رسم می‌شود) ادامه دارد. تو گره‌ها را به app.stage می‌افزایی و رسم‌گر آن‌ها را می‌کشد.

فقط مرورگر. ranuts/visual به یک HTMLCanvasElement واقعی و به بافتار GPU یا Canvas نیاز دارد. در Node اجرا نمی‌شود.

وارد کردن

import { Application, Graphics, Container } from 'ranuts/visual';

آغاز سریع

یک برنامه بساز، مستطیلی با پُرکن و خط دور و یک دایره بکش، و حلقهٔ رسم را به راه بینداز.

import { Application, Graphics, RENDERER_TYPE } from 'ranuts/visual';

const view = document.querySelector('canvas');

// Application.create ناهمگام است: پشتوانهٔ WebGPU دستگاهش را ناهمگام
// آماده می‌کند و این کار باید پیش از نخستین رسم تمام شود.
const app = await Application.create({
  view,
  prefer: RENDERER_TYPE.CANVAS, // CANVAS | WEB_GL | WEB_GPU
  backgroundColor: '#1e1e1e',
});

// یک مستطیل: پُرکن قرمز و خط دورِ آبی ۴ پیکسلی.
const rect = new Graphics();
rect.beginFill('#ff0000');
rect.lineStyle(4, '#0000ff');
rect.drawRect(20, 20, 160, 100);
rect.endFill();

// یک دایره.
const circle = new Graphics();
circle.beginFill('#00cc88', 0.8);
circle.drawCircle(300, 120, 60);
circle.endFill();

// چیزهای رسم‌شدنی را به stage بیفزا؛ نیای هرچه که رسم می‌شود.
app.stage.addChild(rect);
app.stage.addChild(circle);

// حلقهٔ requestAnimationFrame را به راه بینداز (یا برای یک فریم تنها app.render() را صدا بزن).
app.start();

API

Application

نقطهٔ ورود موتور. بوم، رسم‌گر و ریشهٔ گراف صحنه (stage) از آنِ اوست.

به‌جای new Application(...) همان کارخانهٔ ناهمگام Application.create(...) را بردار: پشتوانهٔ WebGPU دستگاهش را ناهمگام آماده می‌کند و این باید پیش از نخستین رسم تمام شود. Canvas و WebGL بی‌درنگ برآورده می‌شوند، پس این کارخانه برای هر سه پشتوانه امن و یکدست است.

Application.create(options)

static async است. یک Application می‌سازد و منتظر آماده‌سازی ناهمگام رسم‌گر می‌ماند.

پارامترها

مقدار بازگشتی

Properties

Methods

IApplicationOptions

Container

گره‌ای برای گروه‌بندی؛ همان مفهوم «گروه» در گراف صحنه. فرزندان و وضعیت دگرگونی را نگه می‌دارد اما خودش چیزی نمی‌کشد؛ چیزهای رسم‌شدنی مانند Graphics از آن ارث می‌برند. وقتی می‌خواهی زیردرختی بسازی که با هم جابه‌جا و بزرگ و چرخانده شود، یک Container بیفزا.

Methods

ویژگی‌های دگرگونی و نمایش

این‌ها بر گرهٔ پایهٔ مشترک (Vertex) نشسته‌اند و روی هر Container و Graphics در دسترس‌اند.

Graphics

چیزی رسم‌شدنی که Container را گسترش می‌دهد. پُرکن یا سبک خط یا هر دو را تعیین کن و سپس یکی از متدهای شکل را صدا بزن. بیشتر متدها this برمی‌گردانند، پس فراخوان‌ها زنجیر می‌شوند.

سبک

شکل‌ها

مسیرها

IFillStyleOptions

ILineStyleOptions

IFillStyleOptions را گسترش می‌دهد و این‌ها را می‌افزاید:

شمارشی‌ها

RENDERER_TYPE

پشتوانهٔ رسم را از راه IApplicationOptions.prefer برمی‌گزیند.

SHAPE_TYPE

گونه‌های شکلی که متدهای رسم Graphics پدید می‌آورند.

LINE_CAP

LINE_JOIN

ثابت‌ها

پشتوانه‌ها

پشتوانه با IApplicationOptions.prefer (از نوع RENDERER_TYPE) برگزیده می‌شود؛ اگر نیاید، Canvas به کار می‌رود.

• CANVAS یکراست با API همان Canvas2D می‌کشد (fillRect، arc، ctx.stroke() و…).
• WEB_GL و WEB_GPU یک خط لولهٔ BatchRenderer را با هم شریک‌اند: شکل‌ها به مثلث خرد می‌شوند، در یک بافر رأس درهم‌بافته جای می‌گیرند و با یک فراخوان کشیده می‌شوند.

هر سه پشتوانه هر رنگ CSS را می‌پذیرند: شانزده‌شانزدهی (#rgb یا #rrggbb)، رنگ‌های نام‌دار، rgb() و hsl() همه یکسان تفسیر می‌شوند.

هندسهٔ خط دور بسته به پشتوانه فرق می‌کند، و این عمدی است. در پشتوانهٔ Canvas، سرها و پیوندهای خط را همان ctx.stroke() بومی مرورگر می‌کشد، اما در WebGL و WebGPU یک مثلث‌بندی دست‌ساز. این دو پیکسل‌به‌پیکسل یکسان نیستند.