نام (NAME)

rgbgfx — مبدل گرافیک Game Boy

خلاصه دستور (SYNOPSIS)

rgbgfx [-CmhOuVwXYZ] [-v [-v ...]] [-a attrmap | -A] [-B color] [-b base_ids] [-c pal_spec] [--color when] [-d depth] [-i input_tiles] [-L slice] [-l base_pal] [-N nb_tiles] [-n nb_pals] [-o out_file] [-p pal_file | -P] [-q pal_map | -Q] [-r width] [-s nb_colors] [-t tilemap | -T] [-W warning] [-x quantity] file

توضیحات (DESCRIPTION)

برنامهٔ rgbgfx تصاویر PNG را به داده‌های مناسب برای نمایش در Game Boy و Game Boy Color یا برعکس تبدیل می‌کند.

کارکرد اصلی rgbgfx تقسیم تصویر PNG ورودی به مربع‌های 8×8 پیکسلی، تبدیل هر یک از آن مربع‌ها به داده‌های کاشی (tile) 1bpp یا 2bpp و ذخیرهٔ تمام داده‌های کاشی در یک فایل است. این برنامه همچنین گزینه‌هایی برای تولید نقشه‌کاشی (tile map)، نقشهٔ صفت (attribute map) و/یا مجموعهٔ پالت دارد؛ توضیحات بیشتر دربارهٔ این موارد و چگونگی تنظیم فرایند تبدیل در ادامه آمده است.

آرگومان‌ها (ARGUMENTS)

rgbgfx گزینه‌های کوتاه و بلند معمول مانند -V و --version را می‌پذیرد. گزینه‌هایی که بعداً در خط فرمان می‌آیند جایگزین گزینه‌های قبلی می‌شوند، مگر در مواردی که تکرار گزینه‌ها خطا در نظر گرفته شود. کوتاه‌نویسی گزینه‌ها تا زمانی که بدون ابهام باشد مجاز است: --verb معادل --verbose است، اما --ver نامعتبر است زیرا می‌تواند نشان‌دهندهٔ --version نیز باشد.

مگر در مواردی که خلاف آن ذکر شده باشد، ارسال ‘-’ (یک خط فاصلهٔ تکی) به عنوان نام فایل باعث می‌شود rgbgfx از ورودی استاندارد (برای فایل‌های ورودی) یا خروجی استاندارد (برای فایل‌های خروجی) استفاده کند. برای جلوگیری از این رفتار، و باز کردن فایلی در دایرکتوری فعلی که واقعاً نام آن ‘-’ است، به جای آن ‘./-’ را ارسال کنید. استفاده از ورودی یا خروجی استاندارد برای بیش از یک فایل در یک دستور واحد ممکن است نتایج غیرمنتظره‌ای به همراه داشته باشد.

rgbgfx اعداد ده‌دهی، شانزده‌شانزدهی، هشت‌هشتی و دودویی را برای آرگومان‌های عددی گزینه‌ها می‌پذیرد. اعداد ده‌دهی مانند معمول نوشته می‌شوند؛ اعداد شانزده‌شانزدهی (hexadecimal) باید با ‘$’ یا ‘0x’ پیشوندگذاری شوند؛ اعداد هشت‌هشتی (octal) باید با ‘&’ یا ‘0o’ و اعداد دودویی (binary) باید با ‘%’ یا ‘0b’ پیشوند داده شوند. (پیشوندهای ‘$’ و ‘&’ احتمالاً برای جلوگیری از تفسیر توسط پوسته، نیاز به گریز (escaping) یا نقل‌قول (quoting) دارند.) صفرهای ابتدایی (پس از پیشوند مبنا، در صورت وجود) پذیرفته می‌شوند و حروف به بزرگی و کوچکی حساس نیستند. برای مثال، تمام این موارد معادل یکدیگرند: ‘42’, ‘042’, ‘0x2A’, ‘0X2A’, ‘0x2a’, ‘&52’, ‘0o52’, ‘0O052’, ‘0b00101010’, ‘0B101010’.

گزینه‌های زیر پذیرفته می‌شوند:

-a attrmap, --attr-map attrmap

تولید یک نقشهٔ صفت (attribute map)، که فایلی حاوی “صفت‌های” کاشی است. برای هر مربع از تصویر ورودی، بایت متناظر آن در نقشهٔ صفت شامل بیت‌های آینه‌ای (در صورتی که -m مشخص شده باشد)، بیت بانک (به -N -مراجعه -کنید), و شاخص پالت (palette index) است. برای ساختار بایت‌های منفرد، به Pan Docs مراجعه کنید. خروجی درست مانند نقشه‌کاشی نوشته می‌شود (به -t مراجعه کنید)، از همان ترتیب پیروی می‌کند (-Z), و اندازهٔ یکسانی دارد.

-A, --auto-attr-map

مشابه -a base_path.attrmap است (مراجعه کنید به Automatic output paths).

-B color, --background-color color

تنظیم رنگ پس‌زمینه‌ای که باید از خروجی حذف شود. رنگ‌ها در قالب ‘#rgb’ یا ‘#rrggbb’ یا به صورت ‘transparent’ پذیرفته می‌شوند. کاشی‌های ورودی که کاملاً به رنگ پس‌زمینهٔ تعیین‌شده باشند نادیده گرفته می‌شوند و در فایل داده‌های کاشی خروجی داده نخواهند شد. فایل‌های tilemap، نقشهٔ صفت یا نقشهٔ پالت در محل کاشی‌های پس‌زمینه حتماً از مقادیر جای‌نگهدار (placeholder) استفاده خواهند کرد. اگر رنگ پس‌زمینه‌ای مشخص شود، نمی‌توان از آن در کاشی‌هایی که نادیده گرفته نشده‌اند استفاده کرد.

-b base_ids, --base-tiles base_ids

تنظیم شناسه‌های پایه (base IDs) برای خروجی نقشه‌کاشی. base_ids باید یک یا دو عدد بین 0 و 255 باشند که با کاما از هم جدا شده‌اند؛ این شناسه‌ها به ترتیب برای bank 0 و bank 1 هستند. پیش‌فرض هر دو 0 است.

-C, --color-curve

پالت‌های رنگی را (چه از تصویر ورودی تولید شده باشند و چه از مشخصات پالت ورودی گرفته شده باشند) با یک منحنی رنگی که شبیه‌ساز صفحه نمایش Game Boy Color است تغییر می‌دهد. این کار مقادیر مطلق رنگ‌های RGB را به‌گونه‌ای تنظیم می‌کند که رنگ‌های درک‌شده هنگام نمایش روی سخت‌افزار Game Boy Color (یا یک شبیه‌ساز با فیلتر نمایش دقیق), شبیه به رنگ‌های اصلی نمایش‌داده‌شده روی یک صفحه نمایش رایانه‌ای دارای نور پس‌زمینه به نظر برسند. توجه داشته باشید که نمایشگرهای GBC بسته به نور محیط و مدل دقیق سخت‌افزاری‌شان می‌توانند بسیار متفاوت به نظر برسند، بنابراین این منحنی رنگ صرفاً یک «بهترین تلاش» (best effort) است.

-c pal_spec, --colors pal_spec

استفاده از پالت‌های رنگی مشخص‌شده به جای آنکه rgbgfx آن‌ها را به صورت خودکار تعیین کند. pal_spec می‌تواند یکی از موارد زیر باشد:

مشخصات پالت درون‌خطی (inline palette spec)

اگر pal_spec با یک نویسهٔ هش ‘#’ آغاز شود، به عنوان مشخصات پالت درون‌خطی در نظر گرفته می‌شود. این مشخصات باید شامل فهرستی از رنگ‌های شانزده‌شانزدهی جداشده با کاما باشد که هر یک با یک هش آغاز می‌شوند. رنگ‌ها در قالب‌های ‘#rgb’ یا ‘#rrggbb’ پذیرفته می‌شوند. برای باقی گذاشتن یک یا چند جای خالی در پالت، می‌توان به جای هر رنگی از ‘#none’ استفاده کرد. پالت‌ها باید با دو نقطه یا نقطه ویرگول از هم جدا شوند (مورد دوم ممکن است برای جلوگیری از تفسیر ویژه توسط پوسته نیاز به نقل‌قول داشته باشد)، و وجود فاصله در اطراف دو نقطه‌ها، نقطه ویرگول‌ها و کاماها مجاز است؛ همچنین وجود کاما و نقطه ویرگول پایانی مجاز است. برای مشاهدهٔ یک نمونه از مشخصات پالت درون‌خطی، به EXAMPLES مراجعه کنید.

مشخصات پالت توکار (embedded palette spec)

اگر pal_spec کلمهٔ غیرحساس به بزرگی و کوچکی حروف embedded باشد، چهار رنگ نخست از پالت توکار تصویر PNG ورودی استفاده می‌شوند. اگر PNG نمایه‌شده (indexed) نباشد، یا اگر رنگ‌هایی غیر از این ۴ رنگ به کار رفته باشند، خطا محسوب می‌شود..Pq این با رفتار پیش‌فرض PNGهای نمایه‌شده متفاوت است، چرا که در آن حالت ورودی‌های استفاده‌نشده در پالت درون‌سازی‌شده نادیده گرفته می‌شوند، در حالی که با Fl c Cm embedded نادیده گرفته نمی‌شوند .

مشخصات پالت DMG

اگر pal_spec با عبارت غیرحساس به بزرگی و کوچکی حروف dmg= آغاز شود، آن‌گاه عدد هگزادسیمال دو رقمی پس از آن، چهار نمایه رنگی DMG در مقیاس خاکستری را مشخص می‌کند. این عدد مشابه ثبات BGP در آدرس $FF47 مربوط به DMG عمل می‌کند (برای اطلاعات بیشتر به Pan Docs مراجعه کنید): دو بیت کم‌ارزش 0-1 مشخص می‌کنند که کدام سایه خاکستری در نمایه رنگ 0 قرار می‌گیرد، دو بیت بعدی 2-3 مشخص می‌کنند که کدام سایه خاکستری در نمایه رنگ 1 قرار می‌گیرد، و به همین ترتیب. سایه خاکستری 0 روشن‌ترین (سفید) و 3 تاریک‌ترین (سیاه) است. اگر pal_spec کلمه غیرحساس به حروف بزرگ و کوچک dmg باشد، آن‌گاه مانند dmg=E4 عمل می‌کند؛ بدین معنی که تاریک‌ترین خاکستری در نمایه رنگ 0 قرار می‌گیرد و به همین ترتیب. یک سایه خاکستری یکسان نمی‌تواند در دو نمایه رنگ قرار گیرد. برای مشخص کردن یک پالت DMG، تمام رنگ‌های تصویر PNG ورودی باید در سایه‌های خاکستری و بدون هیچ‌گونه رنگ شفافی باشند.

تولید خودکار پالت

اگر pal_spec کلمه غیرحساس به حروف بزرگ و کوچک auto باشد، آن‌گاه یک پالت به‌طور خودکار با استفاده از روش شرح داده شده در PALETTE GENERATION تولید می‌شود. این رفتار پیش‌فرض است در صورتی که -c مشخص نشده باشد.

مشخصات پالت خارجی

در غیر این صورت، فرض می‌شود که pal_spec مشخصات یک پالت خارجی است. قالب مورد انتظار به‌صورت ‘format:path’ است، که در آن path مسیری به یک فایل است (‘-’ به‌طور ویژه بررسی نمی‌شود)، که با توجه به format پردازش خواهد شد. برای فهرستی از قالب‌ها و توضیحات آن‌ها به PALETTE SPECIFICATION FORMATS مراجعه کنید.

--color when

تعیین زمان برجسته‌سازی رنگی پیام‌های هشدار و خطا: ‘always ،’ ‘never’ یا ‘auto’. ‘auto’ استفاده از رنگ را بر اساس متغیرهای محیطی ‘NO_COLOR’ یا ‘FORCE_COLOR’ یا این‌که آیا خروجی به یک TTY ارسال می‌شود، تعیین می‌کند.

-d depth, --depth depth

تنظیم عمق بیتی داده‌های تایل خروجی، بر حسب بیت بر پیکسل (bpp)، روی 1 یا 2 (پیش‌فرض). این گزینه نحوه خروجی داده‌های تایل و حداکثر تعداد رنگ‌ها در هر پالت (به‌ترتیب 2 و 4) را تغییر می‌دهد.

-h, --help

چاپ متن راهنمای برنامه و خروج. (اگر متغیر محیطی COLUMNS به‌صورت مقداری غیرصفر تعریف شده باشد، متن راهنما در عرض آن سطرشکنی می‌شود؛ در غیر این صورت به عرض پنجره کنسول، در صورتی که خروجی به یک TTY باشد.)

-i input_tiles, --input-tileset input_tiles

استفاده از تایل‌های ورودی مشخص‌شده علاوه‌بر تعیین خودکار برخی تایل‌ها توسط rgbgfx. تایل‌های ورودی همواره در خروجی تصویر -o در ابتدا قرار می‌گیرند و همیشه نخستین شناسه‌ها را در خروجی نگاشت تایل -t دریافت می‌کنند. input_tiles باید شامل داده‌های تایل 1bpp یا 2bpp باشد (هرکدام که با گزینه -d استفاده‌شده در اینجا مطابقت داشته باشد ،) همان‌طور که قبلاً می‌شد با گزینه -o تولید کرد.

اگر گزینه -o نیز مشخص شده باشد، نخستین شناسه‌های تایل به تایل‌های ورودی اختصاص داده می‌شوند و به هر تایلی از تصویر ورودی که در مجموعه تایل ورودی نباشد، شناسه‌های بعدی اختصاص می‌یابد. اما اگر گزینه -o مشخص نشده باشد، نگاشت تایل تنها می‌تواند از تایل‌های مجموعه تایل ورودی استفاده کند. استفاده از -o همراه با -i زمانی مفید است که بخواهید شناسه‌های تایل نگاشت تایل آن را به‌دقت کنترل کنید. استفاده از -i به‌تنهایی زمانی کاربردی‌تر است که بخواهید چندین تصویر از زیرمجموعه‌ای از تایل‌های مشترک استفاده کنند.

اگر تصویر از بیش از یک پالت رنگی استفاده کند، اکیداً توصیه می‌شود که مجموعه پالت به همراه داده‌های تایل ورودی تولید شده و -c gbc:input_palette همراه با -i input_tiles ارسال شود. دلیل این امر این است که ممکن است rgbgfx همان مجموعه پالتی را که برای مجموعه تایل ورودی آن تولید کرده بود، برای این تصویر تولید نکند.

برای نمونه‌هایی از نحوه استفاده از این گزینه به EXAMPLES مراجعه کنید.

این گزینه در REVERSE MODE نادیده گرفته می‌شود.

-L slice, --slice slice

تنها یک مستطیل مشخص از تصویر را پردازش می‌کند. این قابلیت برای مثال زمانی مفید است که تصویر ورودی نوعی برگه (sheet) باشد و بخواهید هر سلول (cel) را جداگانه تبدیل کنید. پیش‌فرض، پردازش کل تصویر به همان صورت اولیه است.

slice باید به‌صورت ‘X,Y:W,H’: قالب‌بندی شود: دو جفت عدد جداشده با کاما، که با یک دونقطه از یکدیگر تفکیک شده‌اند. فاصله خالی در اطراف تمام علائم نگارشی مجاز است. نخستین جفت عدد مختصات X و Y بالاترین و چپ‌ترین پیکسلی را که پردازش خواهد شد مشخص می‌کند (هر چیزی بالاتر از آن یا در سمت چپ آن نادیده گرفته می‌شود). دومین جفت عدد به‌ترتیب مشخص می‌کند چه تعداد تایل به‌صورت افقی و عمودی پردازش شوند.

-L در حالت معکوس نادیده گرفته می‌شود ، هیچ فاصله‌گذاری درج نمی‌شود.

-l base_pal, --base-palette base_pal

تنظیم شناسه پایه برای خروجی نگاشت ویژگی‌ها و نگاشت پالت. base_pal باید عددی بین 0 تا 255 باشد. مقدار پیش‌فرض آن 0 است.

-m, --mirror-tiles

یکسان‌سازی تایل‌هایی که تصاویر آینه‌ای متقارن افقی و/یا عمودی یکدیگر هستند. تنها یکی از هر تایل یکتا در فایل داده‌های تایل ذخیره می‌شود و تصاویر آینه‌ای به‌عنوان موارد تکراری محسوب می‌شوند. استفاده هم‌زمان با نگاشت تایل و نگاشت ویژگی‌ها مفید است (ببینید -a و -t را) تا تایل‌های تکراری و بُعد(های) آینه‌شده ردیابی شوند. مستلزم -u. معادل با -XY.

-N nb_tiles, --nb-tiles nb_tiles

تنظیم حداکثر تعداد تایل‌هایی که می‌توانند در هر بانک VRAM قرار گیرند. nb_tiles باید یک یا دو عدد بین 0 تا 256 باشد که با کاما از هم جدا شده‌اند؛ اگر عدد دوم حذف شود، مقدار پیش‌فرض آن 0 خواهد بود. تنظیم هر یک از اعداد روی 0 از قرار گرفتن هرگونه تایل در خروجی آن بانک جلوگیری می‌کند.

اگر تایل‌های بیشتری نسبت به گنجایش مجموع دو بانک تولید شود، rgbgfx متوقف می‌شود. اگر -N مشخص نشود، هیچ محدودیتی بر تعداد تایل‌های قرارگرفته در بانک 0 اعمال نخواهد شد و تایل‌ها در بانک 1 قرار نمی‌گیرند.

-n nb_pals, --nb-palettes nb_pals

توقف عملیات در صورتی که بیش از nb_pals پالت تولید شود. این مقدار نباید بیشتر از 256 باشد.

توجه داشته باشید که خروجی نگاشت ویژگی‌ها تنها ۳ بیت برای شناسه پالت دارد، بنابراین تعیین حدی بیشتر از 8 ممکن است داده‌های ناقصی ایجاد کند مگر اینکه به یک نگاشت پالت متکی باشید (گزینه -q را ببینید).

-O, --group-outputs

تنظیم مسیر پایه ‘base path’ بر روی مسیر داده‌های تایل خروجی از -o به جای مسیر تصویر ورودی.Pq نگاه کنید به Sx Automatic output paths .

-o out_file, --output out_file

داده‌های کاشی در قالب محلی 2bpp یا در 1bpp (بسته به -d) در این فایل خروجی داده می‌شود.

-p pal_file, --palette pal_file

مجموعه پالت تصویر در این فایل خروجی داده می‌شود.

-P, --auto-palette

مشابه -p base_path.pal (نگاه کنید به Automatic output paths).

-q pal_map, --palette-map pal_map

نگاشت پالت تصویر در این فایل خروجی داده می‌شود. این گزینه در صورتی مفید است که تصویر ورودی شامل بیش از ۸ پالت باشد، زیرا نگاشت مشخصه فقط حاوی ۳ بیت پایینی شاخص‌های پالت است.

-Q, --auto-palette-map

مشابه -q base_path.palmap (نگاه کنید به Automatic output paths).

-r width, --reverse width

برنامه rgbgfx را به حالت “reverse” می‌برد. در این حالت، به جای تبدیل تصویر PNG به داده‌های Game Boy، rgbgfx تلاش می‌کند فرآیند را معکوس کرده و داده‌های Game Boy را در قالب یک تصویر رندر کند. برای جزئیات بیشتر، بخش REVERSE MODE در زیر را ببینید.

width عرض تصویر تولیدی بر حسب کاشی است. -r -0 عرضی را انتخاب می‌کند تا تصویر تا حد امکان مربعی شود. این گزینه زمانی که عرض اصلی را نمی‌دانید مفید است.

-s nb_colors, --palette-size nb_colors

مشخص می‌کند هر پالت شامل چند رنگ است، از جمله رنگ شفاف در صورت وجود. nb_colors نمی‌تواند بیشتر از ‘1 << depth’ باشد (نگاه کنید به -d).

-t tilemap, --tilemap tilemap

فایلی از شاخص‌های کاشی تولید می‌کند. برای هر مربع از تصویر ورودی، بایت نگاشت کاشی متناظر با آن حاوی شاخص کاشی مرتبط در فایل داده‌های کاشی است. شناسه‌ها پس از ۲۵۵ دوباره به ۰ بازمی‌گردند و شامل بیت بانک نیستند؛ برای آن از -a استفاده کنید. در ترکیب با -u و/یا -m برای پیگیری کاشی‌های تکراری مفید است.

-T, --auto-tilemap

مشابه -t base_path.tilemap (نگاه کنید به Automatic output paths).

-u, --unique-tiles

کاشی‌های یکسان را یکتاسازی می‌کند. از هر کاشی یکتا فقط یک مورد در فایل داده‌های کاشی ذخیره خواهد شد. همراه با نگاشت کاشی (نگاه کنید به -t) برای ردیابی کاشی‌های تکراری مفید است.

توجه داشته باشید که در صورت فعال بودن این گزینه، هیچ تضمینی درباره ترتیب خروجی کاشی‌ها وجود ندارد؛ هرچند این ترتیب باید در اجراهای یکسان از یک نگارش مشخص از rgbgfx پایدار باشد، اما در نگارش‌های مختلف این‌گونه نخواهد بود.

-V, --version

نسخه برنامه را چاپ کرده و خارج می‌شود.

-v, --verbose

حالت پرگو. سطح پرگویی با هر بار مشخص کردن این پرچم یک واحد افزایش می‌یابد و هر سطح شامل سطح قبلی است:

1. چاپ پیکربندی rgbgfx پیش از انجام اقدامات.
2. چاپ یک اعلان پیش از اقدامات مهم.
3. چاپ برخی از نتایج میانی اقدامات.
4. چاپ برخی اطلاعات اشکال‌زدایی داخلی.
5. چاپ اطلاعات داخلی دقیق.

سطح پرگویی از ۶ بالاتر نمی‌رود.

توجه داشته باشید که خروجی پرگو صرفاً برای خوانده شدن توسط انسان در نظر گرفته شده است و ممکن است بدون اطلاع قبلی بین نگارش‌های مختلف RGBDS تغییر کند؛ بنابراین اتکا به آن‌ها در اسکریپت‌ها توصیه نمی‌شود.

-W warning, --warning warning

تنظیم پرچم هشدار warning. اگر warning یک پرچم هشدار ناشناخته باشد، پیام هشداری چاپ خواهد شد. برای فهرستی از هشدارها، بخش DIAGNOSTICS را ببینید.

-w

غیرفعال کردن تمام خروجی‌های هشدار، حتی در صورتی که به خطا تبدیل شده باشند.

-X, --mirror-x

یکتاسازی کاشی‌هایی که تصاویر آینه‌ای متقارن افقی یکدیگر در امتداد محور X هستند. مستلزم -u است.

-x quantity, --trim-end quantity

تعداد quantity کاشی آخر را در فایل داده‌های کاشی خروجی نمی‌دهد؛ هیچ خروجی دیگری تحت تأثیر قرار نمی‌گیرد. این گزینه برای برش دادن مربع‌های “filler” / خالی در انتهای تصویر مفید است. اگر کاشی‌های خروجی کمتر از quantity باشد، فایل خالی خواهد بود.

توجه داشته باشید که اگر -u فعال شده باشد، این کار پس از یکتاسازی انجام می‌شود، بنابراین احتمالاً نمی‌خواهید از این گزینه در ترکیب با -u استفاده کنید. همچنین توجه داشته باشید کاشی‌هایی که خروجی داده نمی‌شوند در محدودیت -N محاسبه نخواهند شد.

-Y, --mirror-y

یکتاسازی کاشی‌هایی که تصاویر آینه‌ای متقارن عمودی یکدیگر در امتداد محور Y هستند. مستلزم -u است.

-Z, --columns

خواندن مربع‌ها از PNG با ترتیب ستون‌محور (ستون به ستون)، به جای ترتیب پیش‌فرض سطر‌محور (خط به خط). این گزینه عمدتاً بر خروجی نگاشت کاشی و نگاشت مشخصه تأثیر می‌گذارد، گرچه ممکن است داده‌های کاشی و پالت‌های تولیدشده را نیز تغییر دهد.

@at_file

خواندن گزینه‌ها و آرگومان‌های بیشتر از یک فایل، گویی محتویات آن در خط فرمان ارائه شده است. آرگومان‌ها با فاصله خالی یا خط جدید از هم جدا می‌شوند. خطوطی که با علامت هش (‘#’) شروع می‌شوند، توضیح تلقی شده و نادیده گرفته می‌شوند.

هیچ پردازش پوسته‌ای، مانند بسط نویسه عام یا بسط متغیرها، انجام نمی‌شود. هیچ پشتیبانی از گریز دادن یا نقل‌قول فواصل خالی برای گنجاندن در آرگومان‌ها وجود ندارد. نشانه استاندارد ‘--’ برای توقف پردازش گزینه‌ها، پردازش at-file را نیز غیرفعال می‌کند. توجه داشته باشید گرچه می‌توان از ‘--’ درون یک at-file استفاده کرد، اما این کار فقط پردازش گزینه را در همان at-file متوقف می‌کند و پردازش در دامنه والد ادامه می‌یابد.

برای توضیحی درباره چگونگی کاربردی بودن این امکان، بخش At-files در زیر را ببینید. در یک پروژه معین، ممکن است نیاز باشد تصاویر متعددی با پرچم‌های متفاوتی تبدیل شوند. روش سنتی برای حل این مسئله، تعیین پرچم‌های مختلف برای هر تصویر در Makefile یا اسکریپت ساخت بوده است؛ این کار می‌تواند ناخوشایند باشد، زیرا تمام این پرچم‌ها را در جایی دور از تصاویری که به آن‌ها مربوط می‌شوند، متمرکز می‌کند.

برای اجتناب از این معایب، می‌توانید از “at-files” استفاده کنید: هر آرگومان خط فرمانی که با علامت ات (‘@’) آغاز شود، همان‌طور که در بالا توضیح داده شد، به عنوان یکی از این فایل‌ها تفسیر می‌شود. فایل‌های At را می‌توان دقیقاً در کنار تصویر مربوطه ذخیره کرد، برای مثال:

$ rgbgfx -o image.2bpp -t image.tilemap @image.flags image.png

این دستور پرچم‌های اضافی را از فایل ‘image.flags’ می‌خواند، که می‌تواند برای نمونه شامل ‘-b 128’ باشد تا یک آفست پایه برای کاشی‌های تصویر مشخص کند. دستور بالا می‌تواند از قاعده make(1) زیر ایجاد شود:

%.2bpp %.tilemap: %.flags %.png
        rgbgfx -o $*.2bpp -t $*.tilemap @$*.flags $*.png

فرمت‌های مشخص‌سازی پالت (PALETTE SPECIFICATION FORMATS)

فرمت‌های زیر پشتیبانی می‌شوند:

act

جدول رنگ Adobe Photoshop.

aco

نمونه رنگ Adobe Photoshop.

gbc

یک روگرفت از حافظه پالت GBC، همان‌طور که توسط rgbgfx -p تولید می‌شود. برای وادار کردن چندین تصویر به اشتراک یک پالت یکسان مفید است.

gpl

پالت GIMP.

hex

خطوط متنی ساده از رنگ‌های هگزادسیمال در قالب ‘rrggbb’

png

تصویری از نمونه‌رنگ‌های مربعی، که هر سطر آن رنگ‌های یک پالت را مشخص می‌کند. اندازه مربع نمونه‌رنگ‌ها می‌تواند هر مقدار دلخواهی باشد.

psp

پالت Paint Shop Pro.

اگر می‌خواهید فرمت دیگری پشتیبانی شود، لطفاً یک گزارش اشکال ثبت کنید (بخش گزارش باگ‌ها (BUGS) در زیر را ببینید) یا با ما تماس بگیرید، و چند فایل نمونه ارائه دهید.

تولید پالت (PALETTE GENERATION)

rgbgfx باید پالت‌ها را از رنگ‌های تصویر ورودی تولید کند، مگر اینکه -c استفاده شده باشد؛ در این حالت، از پالت‌های ارائه‌شده استفاده خواهد شد. اگر ترتیب رنگ‌ها در پالت‌ها برای شما اهمیت دارد, برای مثال به این دلیل که می‌خواهید از تعویض پالت (palette swaps) استفاده کنید، لطفاً از -c برای مشخص کردن صریح پالت استفاده نمایید.

نخست، اگر تصویر حاوی هرگونه پیکسل شفاف باشد، رنگ #0 در تمام پالت‌ها به آن اختصاص داده می‌شود. این کار حتی در صورت تعیین صریح پالت‌ها با -c; انجام می‌شود؛ در این حالت، مشخصات ارائه‌شده تنها رنگ #1 به بعد را پوشش می‌دهد. (اگر این را نمی‌خواهید، از ویرایشگر تصویر خود بخواهید کانال آلفا را حذف کند.)

پس از تولید پالت‌ها، rgbgfx رنگ‌های درون آن پالت‌ها را با استفاده از قواعد زیر مرتب می‌کند:

• اگر فایل PNG در ساختار داخلی خود حاوی یک پالت باشد (که اغلب یک PNG “indexed” نامیده می‌شود)، رنگ‌ها در هر پالت خروجی بر اساس ترتیبشان در پالت PNG مرتب خواهند شد. هر مدخل استفاده‌نشده نادیده گرفته می‌شود و در صورت وجود موارد تکراری، تنها مدخل نخست در نظر گرفته خواهد شد. (اگر می‌خواهید رنگ مشخصی بیش از یک بار ظاهر شود، یا یک رنگ استفاده‌نشده اصلاً حضور داشته باشد، باید در عوض پالت‌ها را صریحاً با -c مشخص کنید؛ -c embedded ممکن است مناسب باشد.)
• در غیر این صورت، اگر PNG تنها حاوی سایه‌های خاکستری باشد، آن‌ها به همان تعدادِ رنگ‌های هر پالت در “دسته‌ها (bins)” دسته‌بندی می‌شوند و پالت روی این دسته‌ها تنظیم می‌گردد. تیره‌ترین خاکستری در دسته #0 قرار می‌گیرد و به همین ترتیب ادامه می‌یابد؛ توجه داشته باشید که این برعکس روش RGB در زیر است. این معادل تعیین پالت DMG به صورت -c dmg=E4 است. اگر دو رنگ خاکستری متمایز در یک دسته قرار گیرند، در عوض از روش RGB استفاده می‌شود.

  توجه داشته باشید که rgbgfx درباره آنچه “خاکستری” می‌داند سخت‌گیر است: مؤلفه‌های قرمز، سبز و آبی هر رنگ باید همگی دقیقاً یکسان باشند.

• اگر هیچ‌یک از موارد بالا صدق نکند، رنگ‌ها از روشن‌ترین (نخست) به تیره‌ترین (آخر) مرتب می‌شوند. تعریفی از درخشندگی (luminance) که rgbgfx به کار می‌برد عبارت است از “ $2126\times \mathrm{red}+7152\times \mathrm{green}+722\times \mathrm{blue}$ ”.

توجه داشته باشید که رفتار “indexed” به یک جزئیات داخلی از نحوه ذخیره شدن PNG وابسته است، به ویژه چانک ‘PLTE’ آن. از آنجا که ویرایشگرهای تصویر اندکی (مانند GIMP) این جزئیات را در دسترس قرار می‌دهند، این رفتار تنها برای سازگاری حفظ شده است و باید منسوخ‌شده در نظر گرفته شود.

مشخص شده است که تولید پالت یک مسئله NP-کامل موسوم به «صفحه‌بندی» (pagination) است، بنابراین rgbgfx تلاشی برای یافتن راه‌حل بهینه نمی‌کند، بلکه در عوض از یک روش اکتشافی (heuristic) موسوم به "overload-and-remove" برای یافتن یک پاسخ مناسب در مدت زمانی معقول استفاده می‌کند. (به جز محدودیت‌های مستندشده در بالا، هیچ تضمینی درباره چگونگی تولید پالت‌ها توسط این الگوریتم وجود ندارد.) امکان محاسبه راه‌حل بهینه به صورت بیرونی (برای مثال با استفاده از یک solver) وجود دارد، که سپس می‌توان آن را از طریق -c به rgbgfx ارائه داد..Sh "فایل‌های خروجی (OUTPUT FILES)" تمام فایل‌های خروجی توسط rgbgfx فایل‌های باینری هستند و به‌گونه‌ای طراحی شده‌اند که از قالب‌های بومی Game Boy و Game Boy Color پیروی کنند. آنچه در ادامه می‌آید توصیف کوتاهی از این قالب‌ها شامل جزئیات اختصاصی rgbgfx است. برای توصیف‌های کامل‌تر، مناسب افراد مبتدی و همراه با تصویرسازی از قالب‌های بومی، لطفاً Pan Docs را بررسی کنید.

$ rgbgfx img/player.png -o build/player.2bpp -P
$ rgbgfx img/player.png -o build/player.2bpp -p img/player.pal

$ rgbgfx img/player.png -o build/player.2bpp -O -P
$ rgbgfx img/player.png -o build/player.2bpp -p build/player.pal

حالت معکوس (REVERSE MODE)

rgbgfx می‌تواند از داده‌های معتبر یک تصویر PNG تولید کند. این قابلیت ممکن است برای استخراج گرافیک‌ها (ripping)، بازیابی تصاویر اصلیِ گم‌شده و غیره مفید باشد. با این حال، یک نکتهٔ مهم در مورد مورد آخر وجود دارد: فرایند تبدیل در هر دو جهت اتلافی (lossy) است، بنابراین تصویر “معکوس‌شده” کاملاً با تصویر اصلی یکسان نخواهد بود—اما به خروجی Game Boy نزدیک خواهد بود. (به یاد داشته باشید که بسیاری از کنسول‌ها رنگ‌های متفاوتی در خروجی تولید می‌کنند، بنابراین هیچ رندر مرجع واقعی وجود ندارد).

هنگام استفاده از حالت معکوس، اطمینان حاصل کنید همان پرچم‌هایی را ارسال می‌کنید که هنگام تولید داده‌ها استفاده شده بودند، به‌ویژه -C, -d, -N, -s, -x, و -Z. بخش “At-files” ممکن است در این زمینه کمک کند. rgbgfx در مورد هرگونه ناسازگاری که شناسایی کند هشدار خواهد داد.

فایل‌هایی که در حالت عادی خروجی هستند (-a, -p, -t) به ورودی تبدیل می‌شوند، و در file به جای خواندن، نوشته خواهد شد، بنابراین نیازی نیست از قبل وجود داشته باشد. هر یک از این ورودی‌ها که ارسال نشوند، روی مقادیر پیش‌فرض فرض می‌شوند:

مثال‌ها (EXAMPLES)

دستور زیر فقط تصویر ‘tileset.png’ را اعتبارسنجی می‌کند (بررسی اندازهٔ آن، اینکه همهٔ تایل‌ها تعداد رنگ مناسبی داشته باشند و غیره)، اما چیزی در خروجی تولید نمی‌کند:

دستور زیر تصویر ‘tileset.png’ را تنها با استفاده از دو پالت ارائه‌شده تبدیل می‌کند و داده‌های تایل 2bpp تولیدشده را در ‘tileset.2bpp’, و نقشهٔ ویژگی‌ها را در ‘tileset.attrmap’ ذخیره خواهد کرد.

دستور زیر تایل‌های تکراری تصویر ‘title_screen.png’ را حذف کرده (تنها یک نسخه از هر تایل یکتا را نگه می‌دارد)، داده‌های تایل 2bpp تولیدشده را در ‘title_screen.2bpp’, و نقشهٔ تایل را در ‘title_screen.tilemap’ ذخیره می‌کند.

دستور زیر مشخصات پالت درون‌خطی ارائه‌شده را به یک مجموعه پالت تبدیل کرده و مجموعه پالت را بدون نیاز به تصویر ورودی در ‘colors.pal’, ذخیره می‌کند.

دستورهای زیر دو تصویر مرحله را با استفاده از یک مجموعه‌تایل یکسان تبدیل می‌کنند و در صورتی که هر یک از آن‌ها حاوی تایل‌هایی باشد که در مجموعه‌تایل نیست، با خطا متوقف می‌شوند.

$ rgbgfx tileset.png -o tileset.2bpp -O -P
$ rgbgfx level1.png -i tileset.2bpp -c gbc:tileset.pal -t level1.tilemap -a level1.attrmap
$ rgbgfx level2.png -i tileset.2bpp -c gbc:tileset.pal -t level2.tilemap -a level2.attrmap
لطفاً باگ‌ها یا اشتباهات موجود در این مستندات را در
GitHub
گزارش کنید.

همچنین ببینید (SEE ALSO)

rgbasm(1), rgblink(1), rgbfix(1), rgbds(7)

مرجع سخت‌افزار Game Boy Pan Docs, به‌ویژه بخش مربوط به گرافیک.

تاریخچه (HISTORY)

rgbgfx در ابتدا توسط stag019 به‌عنوان برنامه‌ای برای بسته‌بندی در RGBDS نوشته شد. این برنامه بعداً توسط ISSOtm بازنویسی شد و در حال حاضر توسط شماری از مشارکت‌کنندگان در https://github.com/gbdev/rgbds نگه‌داری می‌شود.