range

عددی را در بازهٔ کمینه و بیشینهٔ تعیین‌شده نگه می‌دارد.

API

range

بازگشت

آرگومان	توضیح	نوع
number	عددِ مهارشده	number

پارامترها

پارامتر	توضیح	نوع	پیش‌فرض
num	عددی که مهار می‌شود	number	الزامی
min	کمترین مقدار	number	0
max	بیشترین مقدار	number	1

نمونه

کاربرد پایه

import { range } from 'ranuts';

console.log(range(5, 0, 10)); // 5
console.log(range(15, 0, 10)); // 10 (به بیشینه مهار شد)
console.log(range(-5, 0, 10)); // 0 (به کمینه مهار شد)

مهار کردن درصد

import { range } from 'ranuts';

const progress = 150; // 150%
const clamped = range(progress, 0, 100);
console.log(clamped); // 100

بازهٔ دلخواه

import { range } from 'ranuts';

const value = 25;
const clamped = range(value, 10, 20);
console.log(clamped); // 20 (بیرون از بازه بود، پس مهار شد)

مهار کردن مقدار رنگ

import { range } from 'ranuts';

const red = 300; // مقدار RGB باید میان ۰ تا ۲۵۵ باشد
const clamped = range(red, 0, 255);
console.log(clamped); // 255

یادداشت‌ها

1. شیوهٔ مهار: اگر عدد از کمینه کمتر باشد کمینه، اگر از بیشینه بیشتر باشد بیشینه، و در غیر این صورت همان مقدار اصلی برمی‌گردد.
2. بازهٔ پیش‌فرض: از ۰ تا ۱، که برای درصدها و نسبت‌ها مناسب است.
3. کاربرد: معمولاً برای محدود کردن ورودی کاربر و برای حساب کردن مقدار پیشرفت یا رنگ به کار می‌رود.

درون‌یابی و نگاشت دوبارهٔ بازه

درون‌یابی و نگاشت دوبارهٔ بازه به سبک سایه‌زن‌ها: همان ابزارهای پایه‌ای که mix و clamp و smoothstep در GLSL می‌دهند. برای نرم کردن پویانمایی، برای نگاشتن جای پیمایش به کدری، یا برای تبدیل میان بازه‌های عددیِ بی‌ربط به هم به کار می‌آید.

clamp

همان کار range بالا را می‌کند، تنها با ترتیب آرگومان به سبک GLSL: clamp(value, min, max) در برابر range(num, min, max). برای هم‌آهنگی با بقیهٔ این خوشه افزوده شده است؛ هر ترتیبی را که در محل فراخوانی خواناتر است برگزینید.

import { clamp } from 'ranuts/utils';

clamp(150, 0, 100); // 100
clamp(-10, 0, 100); // 0

lerp / inverseLerp

lerp(a, b, t) به اندازهٔ t از a به b درون‌یابی می‌کند (t=0 یعنی a و t=1 یعنی b). inverseLerp(a, b, value) وارونهٔ آن است: با دادن valueای میان a و b، جای آن را همچون 0..1 می‌گوید. هیچ‌کدام مهار نمی‌کنند: اگر value بیرون از [a, b] باشد، t (یا نتیجه) هم از 0..1 بیرون می‌زند.

import { lerp, inverseLerp } from 'ranuts/utils';

lerp(0, 100, 0.25); // 25
inverseLerp(0, 100, 25); // 0.25
inverseLerp(0, 100, 150); // 1.5 — مهار نمی‌شود

پارامترها

تابع	پارامتر	توضیح	نوع
lerp(a, b, t)	a، b	مقدار آغاز و پایان	number
	t	ضریب درون‌یابی	number
inverseLerp(a, b, value)	a، b	مقدار آغاز و پایان	number
	value	مقداری که جایش پرسیده می‌شود	number

remap / fit

remap(value, a1, a2, b1, b2) مقدار value را به‌شکل خطی از [a1, a2] به [b1, b2] می‌نگارد و مهار نمی‌کند. fit گونهٔ مهارکننده است: همان نگاشت، و سپس مهار در بازهٔ خروجی.

import { remap, fit } from 'ranuts/utils';

remap(5, 0, 10, 0, 100); // 50
remap(15, 0, 10, 0, 100); // 150 — بیرون از [0,10] است، پس بیرون از [0,100] هم می‌شود

fit(15, 0, 10, 0, 100); // 100 — در بازهٔ خروجی مهار شد

linearstep / smoothstep

هر دو با رفتن x از edge0 به edge1 از 0 به 1 بالا می‌روند و بیرون از آن بازه مهار می‌شوند. linearstep خطی راست است؛ smoothstep همان منحنی هرمیتِ نرم‌شدهٔ GLSL است (3t² - 2t³)، یعنی آغاز و پایانی نرم به‌جای شیبی راست، و گزینهٔ معمول برای پویانمایی و محوشدگی در سایه‌زن‌ها.

import { linearstep, smoothstep } from 'ranuts/utils';

linearstep(0, 1, 0.5); // 0.5
smoothstep(0, 1, 0.5); // 0.5 (میانه یکی است؛ منحنی در جاهای دیگر فرق دارد)
smoothstep(0, 1, 0.1); // 0.028 — نرم‌شده و کندتر از ۰٫۱ در linearstep از صفر جدا می‌شود

Notes

1. مهار نمی‌کنند: lerp، inverseLerp، remap. اگر value یا tی بیرون از بازهٔ مورد انتظار بدهید، نتیجه‌ای برون‌یابی‌شده می‌گیرید، نه خطا و نه مقداری مهارشده.
2. مهار می‌کنند: fit، linearstep، smoothstep. این سه همیشه مقداری درون بازهٔ خروجی خود می‌دهند.
3. linearstep(edge0, edge1, x) وقتی edge0 === edge1 باشد، به‌جای تقسیم بر صفر، برای x < edge0 مقدار 0 و در غیر آن 1 می‌دهد.