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 می‌سازد و منتظر آماده‌سازی ناهمگام رسم‌گر می‌ماند.

پارامترها

پارامتر	توضیح	نوع	پیش‌فرض
options	گزینه‌های پیکربندی برنامه	IApplicationOptions	الزامی

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

مقدار	توضیح	نوع
Promise<Application>	برنامه‌ای که آماده شده است	Promise<Application>

Properties

ویژگی	توضیح	نوع
stage	ریشهٔ گراف صحنه. هر گره‌ای را که می‌خواهی رسم شود همین‌جا بیفزا.	Container
view	همان عنصر canvas که رسم در آن انجام می‌شود.	HTMLCanvasElement
eventSystem	توزیع اشاره‌گر و رویداد، بسته به canvas و stage.	EventSystem

Methods

متد	توضیح	مقدار بازگشتی
render()	یک فریم تنها از stage را می‌کشد.	void
start()	حلقهٔ رسم requestAnimationFrame را آغاز می‌کند.	void
stop()	حلقهٔ رسمی را که start() آغاز کرده بود متوقف می‌کند.	void

IApplicationOptions

میدان	توضیح	نوع	پیش‌فرض
prefer	اینکه کدام پشتوانه به کار رود. اگر نیاید، به Canvas برمی‌گردد.	RENDERER_TYPE	RENDERER_TYPE.CANVAS
view	بوم مقصد. اگر نیاید، یک <canvas> جدا ساخته می‌شود.	HTMLCanvasElement	یک بوم تازه
backgroundColor	پس‌زمینهٔ بوم. هر رشتهٔ رنگ CSS را می‌پذیرد.	string	—
backgroundAlpha	کدری پس‌زمینه، از 0 تا 1.	number	—
debug	پشتوانهٔ رسمِ برگزیده را در کنسول می‌نویسد.	boolean	false

Container

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

Methods

متد	توضیح	مقدار بازگشتی
addChild(child)	فرزندی (Container) را به انتها می‌افزاید. اگر پیش‌تر پدری داشته، پدرش عوض می‌شود.	void
removeChild(child)	فرزندی را از children برمی‌دارد.	void
sortChildren()	children را بر پایهٔ zIndex از نو مرتب می‌کند (فقط وقتی لازم باشد).	void
containsPoint(p)	وارسی می‌کند که آیا یک Point درون hitArea این گره می‌افتد یا نه.	boolean

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

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

ویژگی	توضیح	نوع
children	گره‌های فرزند (آرایه‌ای فقط‌خواندنی).	Container[]
parent	گرهٔ پدر، اگر پیوسته باشد.	Container | undefined
x / y	جای گره، در دستگاه مختصات پدر.	number
position	نقطهٔ جای‌گیری ({ x, y }).	ObservablePoint
scale	نقطهٔ مقیاس ({ x, y }).	ObservablePoint
pivot	نقطهٔ لولا برای چرخش و مقیاس.	ObservablePoint
skew	نقطهٔ کج‌شدگی.	ObservablePoint
rotation	چرخش بر حسب رادیان.	number
angle	چرخش بر حسب درجه (پابه‌پای rotation).	number
alpha	کدری گره، از 0 تا 1 (پایین‌رونده در درخت ضرب می‌شود).	number
visible	با false، از گره و زیردرختش رد می‌شود.	boolean
zIndex	ترتیب رسم در میان هم‌نیاها.	number
hitArea	شکلی اختیاری برای وارسی برخورد.	Shape | null
cursor	شکل نشانگر وقتی روی گره است.	Cursor
structureVersion	شمارهٔ نسخهٔ ساختار صحنه (فقط در ریشه)؛ ردگیری تغییرها را پیش می‌برد.	number

Graphics

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

سبک

متد	توضیح	مقدار بازگشتی
beginFill(color?, alpha?)	پُر کردن را با color (رشتهٔ CSS، پیش‌فرض '#000000') و alpha (پیش‌فرض 1) آغاز می‌کند.	Graphics
endFill()	پُر کردن را پایان می‌دهد.	Graphics
lineStyle(width, color?, alpha?)	خط دور را تعیین می‌کند: width پیکسل، color (پیش‌فرض '#000000')، alpha (پیش‌فرض 1).	Graphics
lineStyle(options)	خط دور را از روی یک شیء ILineStyleOptions تعیین می‌کند.	Graphics
resetLineStyle()	خط دور کنونی را به مقدارهای پیش‌فرض بازمی‌گرداند.	void

شکل‌ها

متد	توضیح	مقدار بازگشتی
drawRect(x, y, width, height)	مستطیل.	Graphics
drawRoundedRect(x, y, width, height, radius)	مستطیل با گوشه‌های گرد.	Graphics
drawCircle(x, y, radius)	دایره‌ای به مرکز (x, y).	Graphics
drawEllipse(x, y, radiusX, radiusY)	بیضی‌ای به مرکز (x, y).	Graphics
drawPolygon(points)	چندضلعی بسته از روی آرایهٔ تخت [x0, y0, x1, y1, …].	Graphics

مسیرها

متد	توضیح	مقدار بازگشتی
moveTo(x, y)	زیرمسیری تازه از (x, y) آغاز می‌کند.	Graphics
lineTo(x, y)	خط راست تا (x, y).	Graphics
quadraticCurveTo(cpX, cpY, toX, toY)	منحنی بزیه درجه‌دو (به پاره‌خط‌های ریز شکسته می‌شود).	Graphics
bezierCurveTo(cpX, cpY, cpX2, cpY2, toX, toY)	منحنی بزیه درجه‌سه (به پاره‌خط‌های ریز شکسته می‌شود).	Graphics
arc(cx, cy, radius, startAngle, endAngle, anticlockwise?)	کمان دایره.	Graphics
arcTo(x1, y1, x2, y2, radius)	کمانی مماس بر دو خطی که از نقاط کنترل می‌گذرند.	Graphics
closePath()	زیرمسیر کنونی را می‌بندد.	Graphics
clear()	همهٔ هندسه را برمی‌دارد و سبک‌ها را از نو تنظیم می‌کند.	Graphics
containsPoint(p)	وارسی می‌کند که آیا یک Point درون هندسهٔ کشیده‌شده می‌افتد یا نه.	boolean

IFillStyleOptions

میدان	توضیح	نوع	پیش‌فرض
color	رنگ پُرکن (هر رنگ CSS).	string	'#ffffff'
alpha	کدری پُرکن، از 0 تا 1.	number	1
visible	اینکه پُرکن کشیده می‌شود یا نه.	boolean	false

ILineStyleOptions

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

میدان	توضیح	نوع	پیش‌فرض
width	ضخامت خط دور بر حسب پیکسل.	number	0
cap	شکل سرِ خط.	LINE_CAP	LINE_CAP.BUTT
join	شکل پیوند میان خط‌ها.	LINE_JOIN	LINE_JOIN.MITER

شمارشی‌ها

RENDERER_TYPE

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

عضو	مقدار	توضیح
CANVAS	'canvas'	پشتوانهٔ Canvas2D (پیش‌فرض).
WEB_GL	'webgl'	پشتوانهٔ WebGL.
WEB_GPU	'webgpu'	پشتوانهٔ WebGPU.

SHAPE_TYPE

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

عضو	مقدار
RECTANGLE	'rectangle'
POLYGON	'polygon'
CIRCLE	'circle'
ELLIPSE	'ellipse'
ROUNDED_RECTANGLE	'rounded rectangle'

LINE_CAP

عضو	مقدار
BUTT	'butt'
ROUND	'round'
SQUARE	'square'

LINE_JOIN

عضو	مقدار
MITER	'miter'
BEVEL	'bevel'
ROUND	'round'

ثابت‌ها

ثابت	مقدار	توضیح
MAX_VERTEX_COUNT	65536	بیشترین شمار رأسی که هر بافر دسته‌ای برمی‌تابد.
BYTES_PER_VERTEX	12	بایت به ازای هر رأس (دو Float32 برای جای‌گیری و چهار Uint8 برای رنگ).

پشتوانه‌ها

پشتوانه با 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 یک مثلث‌بندی دست‌ساز. این دو پیکسل‌به‌پیکسل یکسان نیستند.