'\" e
.\"
.\" SPDX-License-Identifier: MIT
.\"
.Dd August 1, 2026
.Dt RGBGFX 1
.Os
.Sh "نام (NAME)"
.Nm rgbgfx
.Nd مبدل گرافیک Game Boy
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Fl CmhOuVwXYZ
.Op Fl v Op Fl v No ...
.Op Fl a Ar attrmap | Fl A
.Op Fl B Ar color
.Op Fl b Ar base_ids
.Op Fl c Ar pal_spec
.Op Fl \-color Ar when
.Op Fl d Ar depth
.Op Fl i Ar input_tiles
.Op Fl L Ar slice
.Op Fl l Ar base_pal
.Op Fl N Ar nb_tiles
.Op Fl n Ar nb_pals
.Op Fl o Ar out_file
.Op Fl p Ar pal_file | Fl P
.Op Fl q Ar pal_map | Fl Q
.Op Fl r Ar width
.Op Fl s Ar nb_colors
.Op Fl t Ar tilemap | Fl T
.Op Fl W Ar warning
.Op Fl x Ar quantity
.Ar file
.Sh "توضیحات (DESCRIPTION)"
برنامهٔ
.Nm
تصاویر PNG را به داده‌های مناسب برای نمایش در Game Boy و Game Boy Color یا برعکس تبدیل می‌کند.
.Pp
کارکرد اصلی
.Nm
تقسیم تصویر PNG ورودی به
.Em مربع‌های
8\[tmu]8 پیکسلی، تبدیل هر یک از آن مربع‌ها به داده‌های کاشی (tile) 1bpp یا 2bpp و ذخیرهٔ تمام داده‌های کاشی در یک فایل است.
این برنامه همچنین گزینه‌هایی برای تولید نقشه‌کاشی (tile map)، نقشهٔ صفت (attribute map) و/یا مجموعهٔ پالت دارد؛ توضیحات بیشتر دربارهٔ این موارد و چگونگی تنظیم فرایند تبدیل در ادامه آمده است.
.Sh "آرگومان‌ها (ARGUMENTS)"
.Nm
گزینه‌های کوتاه و بلند معمول مانند
.Fl V
و
.Fl \-version
را می‌پذیرد.
گزینه‌هایی که بعداً در خط فرمان می‌آیند جایگزین گزینه‌های قبلی می‌شوند، مگر در مواردی که تکرار گزینه‌ها خطا در نظر گرفته شود.
کوتاه‌نویسی گزینه‌ها تا زمانی که بدون ابهام باشد مجاز است:
.Fl \-verb
معادل
.Fl \-verbose
است، اما
.Fl \-ver
نامعتبر است زیرا می‌تواند نشان‌دهندهٔ
.Fl \-version
نیز باشد.
.Pp
مگر در مواردی که خلاف آن ذکر شده باشد، ارسال
.Ql -
(یک خط فاصلهٔ تکی) به عنوان نام فایل باعث می‌شود
.Nm
از ورودی استاندارد (برای فایل‌های ورودی) یا خروجی استاندارد (برای فایل‌های خروجی) استفاده کند.
برای جلوگیری از این رفتار، و باز کردن فایلی در دایرکتوری فعلی که واقعاً نام آن
.Ql -
است، به جای آن
.Ql ./-
را ارسال کنید.
استفاده از ورودی یا خروجی استاندارد برای بیش از یک فایل در یک دستور واحد ممکن است نتایج غیرمنتظره‌ای به همراه داشته باشد.
.Pp
.Nm
اعداد ده‌دهی، شانزده‌شانزدهی، هشت‌هشتی و دودویی را برای آرگومان‌های عددی گزینه‌ها می‌پذیرد.
اعداد ده‌دهی مانند معمول نوشته می‌شوند؛ اعداد شانزده‌شانزدهی (hexadecimal) باید با
.Ql $
یا
.Ql 0x
پیشوندگذاری شوند؛ اعداد هشت‌هشتی (octal) باید با
.Ql &
یا
.Ql 0o
و اعداد دودویی (binary) باید با
.Ql %
یا
.Ql 0b
پیشوند داده شوند.
(پیشوندهای
.Ql $
و
.Ql &
احتمالاً برای جلوگیری از تفسیر توسط پوسته، نیاز به گریز (escaping) یا نقل‌قول (quoting) دارند.)
صفرهای ابتدایی (پس از پیشوند مبنا، در صورت وجود) پذیرفته می‌شوند و حروف به بزرگی و کوچکی حساس نیستند.
برای مثال، تمام این موارد معادل یکدیگرند:
.Ql 42 ,
.Ql 042 ,
.Ql 0x2A ,
.Ql 0X2A ,
.Ql 0x2a ,
.Ql &52 ,
.Ql 0o52 ,
.Ql 0O052 ,
.Ql 0b00101010 ,
.Ql 0B101010 .
.Pp
گزینه‌های زیر پذیرفته می‌شوند:
.Bl -tag -width Ds
.It Fl a Ar attrmap , Fl \-attr-map Ar attrmap
تولید یک نقشهٔ صفت (attribute map)، که فایلی حاوی
.Dq صفت‌های
کاشی است.
برای هر مربع از تصویر ورودی، بایت متناظر آن در نقشهٔ صفت شامل بیت‌های آینه‌ای (در صورتی که
.Fl m
مشخص شده باشد)، بیت بانک
.Pq به Fl N مراجعه کنید ,
و شاخص پالت (palette index) است.
برای ساختار بایت‌های منفرد، به
.Lk https://gbdev.io/pandocs/Tile_Maps#bg-map-attributes-cgb-mode-only Pan Docs
مراجعه کنید.
خروجی درست مانند نقشه‌کاشی نوشته می‌شود (به
.Fl t
مراجعه کنید)، از همان ترتیب پیروی می‌کند
.Pq Fl Z ,
و اندازهٔ یکسانی دارد.
.It Fl A , Fl \-auto-attr-map
مشابه
.Fl a Ar base_path Ns .attrmap
است
.Pq مراجعه کنید به Sx Automatic output paths .
.It Fl B Ar color , Fl \-background-color Ar color
تنظیم رنگ پس‌زمینه‌ای که باید از خروجی حذف شود.
رنگ‌ها در قالب
.Ql #rgb
یا
.Ql #rrggbb
یا به صورت
.Ql transparent
پذیرفته می‌شوند.
کاشی‌های ورودی که کاملاً به رنگ پس‌زمینهٔ تعیین‌شده باشند نادیده گرفته می‌شوند و در فایل داده‌های کاشی خروجی داده نخواهند شد.
فایل‌های tilemap، نقشهٔ صفت یا نقشهٔ پالت در محل کاشی‌های پس‌زمینه
.Em حتماً
از مقادیر جای‌نگهدار (placeholder) استفاده خواهند کرد.
اگر رنگ پس‌زمینه‌ای مشخص شود، نمی‌توان از آن در کاشی‌هایی که نادیده گرفته نشده‌اند استفاده کرد.
.It Fl b Ar base_ids , Fl \-base-tiles Ar base_ids
تنظیم شناسه‌های پایه (base IDs) برای خروجی نقشه‌کاشی.
.Ar base_ids
باید یک یا دو عدد بین 0 و 255 باشند که با کاما از هم جدا شده‌اند؛ این شناسه‌ها به ترتیب برای bank 0 و bank 1 هستند.
پیش‌فرض هر دو 0 است.
.It Fl C , Fl \-color-curve
پالت‌های رنگی را
.Pq چه از تصویر ورودی تولید شده باشند و چه از مشخصات پالت ورودی گرفته شده باشند
با یک منحنی رنگی که شبیه‌ساز صفحه نمایش Game Boy Color است تغییر می‌دهد.
این کار مقادیر
.Em مطلق
رنگ‌های RGB را به‌گونه‌ای تنظیم می‌کند که رنگ‌های
.Em درک‌شده
هنگام نمایش روی سخت‌افزار Game Boy Color
.Pq یا یک شبیه‌ساز با فیلتر نمایش دقیق ,
شبیه به رنگ‌های اصلی نمایش‌داده‌شده روی یک صفحه نمایش رایانه‌ای دارای نور پس‌زمینه به نظر برسند.
توجه داشته باشید که نمایشگرهای GBC بسته به نور محیط و مدل دقیق سخت‌افزاری‌شان می‌توانند بسیار متفاوت به نظر برسند، بنابراین این منحنی رنگ صرفاً یک «بهترین تلاش» (best effort) است.
.It Fl c Ar pal_spec , Fl \-colors Ar pal_spec
استفاده از پالت‌های رنگی مشخص‌شده به جای آنکه
.Nm
آن‌ها را به صورت خودکار تعیین کند.
.Ar pal_spec
می‌تواند یکی از موارد زیر باشد:
.Bl -tag -width Ds
.It Sy مشخصات پالت درون‌خطی (inline palette spec)
اگر
.Ar pal_spec
با یک نویسهٔ هش
.Ql #
آغاز شود، به عنوان مشخصات پالت درون‌خطی در نظر گرفته می‌شود.
این مشخصات باید شامل فهرستی از رنگ‌های شانزده‌شانزدهی جداشده با کاما باشد که هر یک با یک هش آغاز می‌شوند.
رنگ‌ها در قالب‌های
.Ql #rgb
یا
.Ql #rrggbb
پذیرفته می‌شوند.
برای باقی گذاشتن یک یا چند جای خالی در پالت، می‌توان به جای هر رنگی از
.Ql #none
استفاده کرد.
پالت‌ها باید با دو نقطه یا نقطه ویرگول از هم جدا شوند (مورد دوم ممکن است برای جلوگیری از تفسیر ویژه توسط پوسته نیاز به نقل‌قول داشته باشد)، و وجود فاصله در اطراف دو نقطه‌ها، نقطه ویرگول‌ها و کاماها مجاز است؛ همچنین وجود کاما و نقطه ویرگول پایانی مجاز است.
برای مشاهدهٔ یک نمونه از مشخصات پالت درون‌خطی، به
.Sx EXAMPLES
مراجعه کنید.
.It Sy مشخصات پالت توکار (embedded palette spec)
اگر
.Ar pal_spec
کلمهٔ غیرحساس به بزرگی و کوچکی حروف
.Cm embedded
باشد، چهار رنگ نخست از پالت توکار تصویر PNG ورودی استفاده می‌شوند.
اگر PNG نمایه‌شده (indexed) نباشد، یا اگر رنگ‌هایی غیر از این ۴ رنگ به کار رفته باشند، خطا محسوب می‌شود..Pq این با رفتار پیش‌فرض PNGهای نمایه‌شده متفاوت است، چرا که در آن حالت ورودی‌های استفاده‌نشده در پالت درون‌سازی‌شده نادیده گرفته می‌شوند، در حالی که با Fl c Cm embedded نادیده گرفته نمی‌شوند .
.It Sy مشخصات پالت DMG
اگر
.Ar pal_spec
با عبارت غیرحساس به بزرگی و کوچکی حروف
.Cm dmg=
آغاز شود، آن‌گاه عدد هگزادسیمال دو رقمی پس از آن، چهار نمایه رنگی DMG در مقیاس خاکستری را مشخص می‌کند.
این عدد مشابه ثبات
.Sy BGP
در آدرس $FF47 مربوط به DMG عمل می‌کند
(برای اطلاعات بیشتر به
.Lk https://gbdev.io/pandocs/Palettes.html Pan Docs
مراجعه کنید):
دو بیت کم‌ارزش 0-1 مشخص می‌کنند که کدام سایه خاکستری در نمایه رنگ 0 قرار می‌گیرد،
دو بیت بعدی 2-3 مشخص می‌کنند که کدام سایه خاکستری در نمایه رنگ 1 قرار می‌گیرد،
و به همین ترتیب.
سایه خاکستری 0 روشن‌ترین (سفید) و 3 تاریک‌ترین (سیاه) است.
اگر
.Ar pal_spec
کلمه غیرحساس به حروف بزرگ و کوچک
.Cm dmg
باشد، آن‌گاه مانند
.Cm dmg=E4
عمل می‌کند؛ بدین معنی که تاریک‌ترین خاکستری در نمایه رنگ 0 قرار می‌گیرد و به همین ترتیب.
یک سایه خاکستری یکسان نمی‌تواند در دو نمایه رنگ قرار گیرد.
برای مشخص کردن یک پالت DMG، تمام رنگ‌های تصویر PNG ورودی باید در سایه‌های خاکستری و بدون هیچ‌گونه رنگ شفافی باشند.
.It Sy تولید خودکار پالت
اگر
.Ar pal_spec
کلمه غیرحساس به حروف بزرگ و کوچک
.Cm auto
باشد، آن‌گاه یک پالت به‌طور خودکار با استفاده از روش شرح داده شده در
.Sx PALETTE GENERATION
تولید می‌شود.
این رفتار پیش‌فرض است در صورتی که
.Fl c
مشخص نشده باشد.
.It Sy مشخصات پالت خارجی
در غیر این صورت، فرض می‌شود که
.Ar pal_spec
مشخصات یک پالت خارجی است.
قالب مورد انتظار به‌صورت
.Ql format:path
است، که در آن
.Ar path
مسیری به یک فایل است
.Ql ( \-
به‌طور ویژه بررسی نمی‌شود)، که با توجه به
.Ar format
پردازش خواهد شد.
برای فهرستی از قالب‌ها و توضیحات آن‌ها به
.Sx PALETTE SPECIFICATION FORMATS
مراجعه کنید.
.El
.It Fl \-color Ar when
تعیین زمان برجسته‌سازی رنگی پیام‌های هشدار و خطا:
.Ql always ،
.Ql never
یا
.Ql auto .
.Ql auto
استفاده از رنگ را بر اساس متغیرهای محیطی
.Ql Lk https://no-color.org NO_COLOR
یا
.Ql Lk https://force-color.org FORCE_COLOR
یا این‌که آیا خروجی به یک TTY ارسال می‌شود، تعیین می‌کند.
.It Fl d Ar depth , Fl \-depth Ar depth
تنظیم عمق بیتی داده‌های تایل خروجی، بر حسب بیت بر پیکسل (bpp)، روی 1 یا 2 (پیش‌فرض).
این گزینه نحوه خروجی داده‌های تایل و حداکثر تعداد رنگ‌ها در هر پالت (به‌ترتیب 2 و 4) را تغییر می‌دهد.
.It Fl h , Fl \-help
چاپ متن راهنمای برنامه و خروج.
(اگر متغیر محیطی
.Dv COLUMNS
به‌صورت مقداری غیرصفر تعریف شده باشد، متن راهنما در عرض آن سطرشکنی می‌شود؛ در غیر این صورت به عرض پنجره کنسول، در صورتی که خروجی به یک TTY باشد.)
.It Fl i Ar input_tiles , Fl \-input-tileset Ar input_tiles
استفاده از تایل‌های ورودی مشخص‌شده علاوه‌بر تعیین خودکار برخی تایل‌ها توسط
.Nm .
تایل‌های ورودی همواره در خروجی تصویر
.Fl o
در ابتدا قرار می‌گیرند و همیشه نخستین شناسه‌ها را در خروجی نگاشت تایل
.Fl t
دریافت می‌کنند.
.Ar input_tiles
باید شامل داده‌های تایل 1bpp یا 2bpp باشد
.Pq هرکدام که با گزینه Fl d No استفاده‌شده در اینجا مطابقت داشته باشد ،
همان‌طور که قبلاً می‌شد با گزینه
.Fl o
تولید کرد.
.Pp
اگر گزینه
.Fl o
نیز مشخص شده باشد، نخستین شناسه‌های تایل به تایل‌های ورودی اختصاص داده می‌شوند و به هر تایلی از تصویر ورودی که در مجموعه تایل ورودی نباشد، شناسه‌های بعدی اختصاص می‌یابد.
اما اگر گزینه
.Fl o
مشخص
.Em نشده
باشد، نگاشت تایل
.Em تنها
می‌تواند از تایل‌های مجموعه تایل ورودی استفاده کند.
استفاده از
.Fl o
همراه با
.Fl i
زمانی مفید است که بخواهید شناسه‌های تایل نگاشت تایل آن را به‌دقت کنترل کنید.
استفاده از
.Fl i
به‌تنهایی زمانی کاربردی‌تر است که بخواهید چندین تصویر از زیرمجموعه‌ای از تایل‌های مشترک استفاده کنند.
.Pp
اگر تصویر از بیش از یک پالت رنگی استفاده کند،
.Em اکیداً
توصیه می‌شود که مجموعه پالت به همراه داده‌های تایل ورودی تولید شده و
.Fl c Cm gbc: Ns Ar input_palette
همراه با
.Fl i Ar input_tiles
ارسال شود.
دلیل این امر این است که ممکن است
.Nm
همان مجموعه پالتی را که برای مجموعه تایل ورودی آن تولید کرده بود، برای این تصویر تولید نکند.
.Pp
برای نمونه‌هایی از نحوه استفاده از این گزینه به
.Sx EXAMPLES
مراجعه کنید.
.Pp
این گزینه در
.Sx REVERSE MODE
نادیده گرفته می‌شود.
.It Fl L Ar slice , Fl \-slice Ar slice
تنها یک مستطیل مشخص از تصویر را پردازش می‌کند.
این قابلیت برای مثال زمانی مفید است که تصویر ورودی نوعی برگه (sheet) باشد و بخواهید هر سلول (cel) را جداگانه تبدیل کنید.
پیش‌فرض، پردازش کل تصویر به همان صورت اولیه است.
.Pp
.Ar slice
باید به‌صورت
.Ql Ar X , Ns Ar Y : Ns Ar W , Ns Ar H :
قالب‌بندی شود: دو جفت عدد جداشده با کاما، که با یک دونقطه از یکدیگر تفکیک شده‌اند.
فاصله خالی در اطراف تمام علائم نگارشی مجاز است.
نخستین جفت عدد مختصات X و Y بالاترین و چپ‌ترین پیکسلی را که پردازش خواهد شد مشخص می‌کند (هر چیزی بالاتر از آن یا در سمت چپ آن نادیده گرفته می‌شود).
دومین جفت عدد به‌ترتیب مشخص می‌کند چه تعداد تایل به‌صورت افقی و عمودی پردازش شوند.
.Pp
.Fl L
.Sy در حالت معکوس نادیده گرفته می‌شود ،
.No هیچ فاصله‌گذاری درج نمی‌شود .
.It Fl l Ar base_pal , Fl \-base-palette Ar base_pal
تنظیم شناسه پایه برای خروجی نگاشت ویژگی‌ها و نگاشت پالت.
.Ar base_pal
باید عددی بین 0 تا 255 باشد.
مقدار پیش‌فرض آن 0 است.
.It Fl m , Fl \-mirror-tiles
یکسان‌سازی تایل‌هایی که تصاویر آینه‌ای متقارن افقی و/یا عمودی یکدیگر هستند.
تنها یکی از هر تایل یکتا در فایل داده‌های تایل ذخیره می‌شود و تصاویر آینه‌ای به‌عنوان موارد تکراری محسوب می‌شوند.
استفاده هم‌زمان با نگاشت تایل و نگاشت ویژگی‌ها مفید است (ببینید
.Fl a
و
.Fl t
را) تا تایل‌های تکراری و بُعد(های) آینه‌شده ردیابی شوند.
مستلزم
.Fl u .
معادل با
.Fl XY .
.It Fl N Ar nb_tiles , Fl \-nb-tiles Ar nb_tiles
تنظیم حداکثر تعداد تایل‌هایی که می‌توانند در هر بانک VRAM قرار گیرند.
.Ar nb_tiles
باید یک یا دو عدد بین 0 تا 256 باشد که با کاما از هم جدا شده‌اند؛ اگر عدد دوم حذف شود، مقدار پیش‌فرض آن 0 خواهد بود.
تنظیم هر یک از اعداد روی 0 از قرار گرفتن هرگونه تایل در خروجی آن بانک جلوگیری می‌کند.
.Pp
اگر تایل‌های بیشتری نسبت به گنجایش مجموع دو بانک تولید شود،
.Nm
متوقف می‌شود.
اگر
.Fl N
مشخص نشود، هیچ محدودیتی بر تعداد تایل‌های قرارگرفته در بانک 0 اعمال نخواهد شد و تایل‌ها در بانک 1 قرار نمی‌گیرند.
.It Fl n Ar nb_pals , Fl \-nb-palettes Ar nb_pals
توقف عملیات در صورتی که بیش از
.Ar nb_pals
پالت تولید شود.
این مقدار نباید بیشتر از 256 باشد.
.Pp
توجه داشته باشید که خروجی نگاشت ویژگی‌ها تنها ۳ بیت برای شناسه پالت دارد، بنابراین تعیین حدی بیشتر از 8 ممکن است داده‌های ناقصی ایجاد کند مگر اینکه به یک نگاشت پالت متکی باشید
.Pq گزینه Fl q No را ببینید .
.It Fl O , Fl \-group-outputs
تنظیم مسیر پایه
.Sq base path
بر روی مسیر داده‌های تایل خروجی از
.Fl o
به جای مسیر تصویر ورودی.Pq نگاه کنید به Sx Automatic output paths .
.It Fl o Ar out_file , Fl \-output Ar out_file
داده‌های کاشی در قالب محلی 2bpp یا در 1bpp
.Pq بسته به Fl d
در این فایل خروجی داده می‌شود.
.It Fl p Ar pal_file , Fl \-palette Ar pal_file
مجموعه پالت تصویر در این فایل خروجی داده می‌شود.
.It Fl P , Fl \-auto-palette
مشابه
.Fl p Ar base_path Ns .pal
.Pq نگاه کنید به Sx Automatic output paths .
.It Fl q Ar pal_map , Fl \-palette-map Ar pal_map
نگاشت پالت تصویر در این فایل خروجی داده می‌شود.
این گزینه در صورتی مفید است که تصویر ورودی شامل بیش از ۸ پالت باشد، زیرا نگاشت مشخصه فقط حاوی ۳ بیت پایینی شاخص‌های پالت است.
.It Fl Q , Fl \-auto-palette-map
مشابه
.Fl q Ar base_path Ns .palmap
.Pq نگاه کنید به Sx Automatic output paths .
.It Fl r Ar width , Fl \-reverse Ar width
برنامه
.Nm
را به حالت
.Dq Sy reverse
می‌برد.
در این حالت، به جای تبدیل تصویر PNG به داده‌های Game Boy،
.Nm
تلاش می‌کند فرآیند را معکوس کرده و داده‌های Game Boy را در قالب یک تصویر رندر کند.
برای جزئیات بیشتر، بخش
.Sx REVERSE MODE
در زیر را ببینید.
.Pp
.Ar width
عرض تصویر تولیدی بر حسب کاشی است.
.Fl r 0
عرضی را انتخاب می‌کند تا تصویر تا حد امکان مربعی شود.
این گزینه زمانی که عرض اصلی را نمی‌دانید مفید است.
.It Fl s Ar nb_colors , Fl \-palette-size Ar nb_colors
مشخص می‌کند هر پالت شامل چند رنگ است، از جمله رنگ شفاف در صورت وجود.
.Ar nb_colors
نمی‌تواند بیشتر از
.Ql 1 << Ar depth
باشد
.Pq نگاه کنید به Fl d .
.It Fl t Ar tilemap , Fl \-tilemap Ar tilemap
فایلی از شاخص‌های کاشی تولید می‌کند.
برای هر مربع از تصویر ورودی، بایت نگاشت کاشی متناظر با آن حاوی شاخص کاشی مرتبط در فایل داده‌های کاشی است.
شناسه‌ها پس از ۲۵۵ دوباره به ۰ بازمی‌گردند و شامل بیت بانک نیستند؛ برای آن از
.Fl a
استفاده کنید.
در ترکیب با
.Fl u
و/یا
.Fl m
برای پیگیری کاشی‌های تکراری مفید است.
.It Fl T , Fl \-auto-tilemap
مشابه
.Fl t Ar base_path Ns .tilemap
.Pq نگاه کنید به Sx Automatic output paths .
.It Fl u , Fl \-unique-tiles
کاشی‌های یکسان را یکتاسازی می‌کند.
از هر کاشی یکتا فقط یک مورد در فایل داده‌های کاشی ذخیره خواهد شد.
همراه با نگاشت کاشی
.Pq نگاه کنید به Fl t
برای ردیابی کاشی‌های تکراری مفید است.
.Pp
توجه داشته باشید که در صورت فعال بودن این گزینه، هیچ تضمینی درباره ترتیب خروجی کاشی‌ها وجود ندارد؛ هرچند این ترتیب
.Em باید
در اجراهای یکسان از یک نگارش مشخص از
.Nm
پایدار باشد، اما در نگارش‌های مختلف این‌گونه نخواهد بود.
.It Fl V , Fl \-version
نسخه برنامه را چاپ کرده و خارج می‌شود.
.It Fl v , Fl \-verbose
حالت پرگو.
سطح پرگویی با هر بار مشخص کردن این پرچم یک واحد افزایش می‌یابد و هر سطح شامل سطح قبلی است:
.Bl -enum -compact
.It
چاپ پیکربندی
.Nm
پیش از انجام اقدامات.
.It
چاپ یک اعلان پیش از اقدامات مهم.
.It
چاپ برخی از نتایج میانی اقدامات.
.It
چاپ برخی اطلاعات اشکال‌زدایی داخلی.
.It
چاپ اطلاعات داخلی دقیق.
.El
سطح پرگویی از ۶ بالاتر نمی‌رود.
.Pp
توجه داشته باشید که خروجی پرگو صرفاً برای خوانده شدن توسط انسان در نظر گرفته شده است و ممکن است بدون اطلاع قبلی بین نگارش‌های مختلف RGBDS تغییر کند؛ بنابراین اتکا به آن‌ها در اسکریپت‌ها توصیه نمی‌شود.
.It Fl W Ar warning , Fl \-warning Ar warning
تنظیم پرچم هشدار
.Ar warning .
اگر
.Ar warning
یک پرچم هشدار ناشناخته باشد، پیام هشداری چاپ خواهد شد.
برای فهرستی از هشدارها، بخش
.Sx DIAGNOSTICS
را ببینید.
.It Fl w
غیرفعال کردن تمام خروجی‌های هشدار، حتی در صورتی که به خطا تبدیل شده باشند.
.It Fl X , Fl \-mirror-x
یکتاسازی کاشی‌هایی که تصاویر آینه‌ای متقارن افقی یکدیگر در امتداد محور X هستند.
مستلزم
.Fl u
است.
.It Fl x Ar quantity , Fl \-trim-end Ar quantity
تعداد
.Ar quantity
کاشی آخر را در فایل داده‌های کاشی خروجی نمی‌دهد؛ هیچ خروجی دیگری تحت تأثیر قرار نمی‌گیرد.
این گزینه برای برش دادن مربع‌های
.Dq filler
/ خالی در انتهای تصویر مفید است.
اگر کاشی‌های خروجی کمتر از
.Ar quantity
باشد، فایل خالی خواهد بود.
.Pp
توجه داشته باشید که اگر
.Fl u
فعال شده باشد، این کار
.Em پس از
یکتاسازی انجام می‌شود، بنابراین احتمالاً نمی‌خواهید از این گزینه در ترکیب با
.Fl u
استفاده کنید.
همچنین توجه داشته باشید کاشی‌هایی که خروجی داده نمی‌شوند در محدودیت
.Fl N
محاسبه نخواهند شد.
.It Fl Y , Fl \-mirror-y
یکتاسازی کاشی‌هایی که تصاویر آینه‌ای متقارن عمودی یکدیگر در امتداد محور Y هستند.
مستلزم
.Fl u
است.
.It Fl Z , Fl \-columns
خواندن مربع‌ها از PNG با ترتیب ستون‌محور (ستون به ستون)، به جای ترتیب پیش‌فرض سطر‌محور (خط به خط).
این گزینه عمدتاً بر خروجی نگاشت کاشی و نگاشت مشخصه تأثیر می‌گذارد، گرچه ممکن است داده‌های کاشی و پالت‌های تولیدشده را نیز تغییر دهد.
.It @ Ns Ar at_file
خواندن گزینه‌ها و آرگومان‌های بیشتر از یک فایل، گویی محتویات آن در خط فرمان ارائه شده است.
آرگومان‌ها با فاصله خالی یا خط جدید از هم جدا می‌شوند.
خطوطی که با علامت هش
.Pq Ql #
شروع می‌شوند، توضیح تلقی شده و نادیده گرفته می‌شوند.
.Pp
هیچ پردازش پوسته‌ای، مانند بسط نویسه عام یا بسط متغیرها، انجام نمی‌شود.
هیچ پشتیبانی از گریز دادن یا نقل‌قول فواصل خالی برای گنجاندن در آرگومان‌ها وجود ندارد.
نشانه استاندارد
.Ql --
برای توقف پردازش گزینه‌ها، پردازش at-file را نیز غیرفعال می‌کند.
توجه داشته باشید گرچه می‌توان از
.Ql --
.Em درون
یک at-file استفاده کرد، اما این کار فقط پردازش گزینه را در همان at-file متوقف می‌کند و پردازش در دامنه والد ادامه می‌یابد.
.Pp
برای توضیحی درباره چگونگی کاربردی بودن این امکان، بخش
.Sx At-files
در زیر را ببینید.
.El.Ss "فایل‌های At (At-files)"
در یک پروژه معین، ممکن است نیاز باشد تصاویر متعددی با پرچم‌های متفاوتی تبدیل شوند.
روش سنتی برای حل این مسئله، تعیین پرچم‌های مختلف برای هر تصویر در Makefile یا اسکریپت ساخت بوده است؛ این کار می‌تواند ناخوشایند باشد، زیرا تمام این پرچم‌ها را در جایی دور از تصاویری که به آن‌ها مربوط می‌شوند، متمرکز می‌کند.
.Pp
برای اجتناب از این معایب، می‌توانید از
.Dq at-files
استفاده کنید: هر آرگومان خط فرمانی که با علامت ات
.Pq Ql @
آغاز شود، همان‌طور که در بالا توضیح داده شد، به عنوان یکی از این فایل‌ها تفسیر می‌شود.
فایل‌های At را می‌توان دقیقاً در کنار تصویر مربوطه ذخیره کرد، برای مثال:
.Pp
.Dl $ rgbgfx -o image.2bpp -t image.tilemap @image.flags image.png
.Pp
این دستور پرچم‌های اضافی را از فایل
.Ql image.flags
می‌خواند، که می‌تواند برای نمونه شامل
.Ql -b 128
باشد تا یک آفست پایه برای کاشی‌های تصویر مشخص کند.
دستور بالا می‌تواند از قاعده
.Xr make 1
زیر ایجاد شود:
.Bd -literal -offset indent
%.2bpp %.tilemap: %.flags %.png
        rgbgfx -o $*.2bpp -t $*.tilemap @$*.flags $*.png
.Ed
.Sh "فرمت‌های مشخص‌سازی پالت (PALETTE SPECIFICATION FORMATS)"
فرمت‌های زیر پشتیبانی می‌شوند:
.Bl -tag -width Ds
.It Cm act
.Lk https://www.adobe.com/devnet-apps/photoshop/fileformatashtml/#50577411_pgfId-1070626 "جدول رنگ Adobe Photoshop" .
.It Cm aco
.Lk https://www.adobe.com/devnet-apps/photoshop/fileformatashtml/#50577411_pgfId-1055819 "نمونه رنگ Adobe Photoshop" .
.It Cm gbc
یک روگرفت از حافظه پالت GBC، همان‌طور که توسط
.Nm Fl p
تولید می‌شود. برای وادار کردن چندین تصویر به اشتراک یک پالت یکسان مفید است.
.It Cm gpl
.Lk https://docs.gimp.org/2.10/en/gimp-concepts-palettes.html "پالت GIMP" .
.It Cm hex
خطوط متنی ساده از رنگ‌های هگزادسیمال در قالب
.Ql rrggbb
.
.It Cm png
تصویری از نمونه‌رنگ‌های مربعی، که هر سطر آن رنگ‌های یک پالت را مشخص می‌کند.
اندازه مربع نمونه‌رنگ‌ها می‌تواند هر مقدار دلخواهی باشد.
.It Cm psp
.Lk https://www.selapa.net/swatches/colors/fileformats.php#psp_pal "پالت Paint Shop Pro" .
.El
.Pp
اگر می‌خواهید فرمت دیگری پشتیبانی شود، لطفاً یک گزارش اشکال ثبت کنید (بخش
.Sx "گزارش باگ‌ها (BUGS)"
در زیر را ببینید) یا با ما تماس بگیرید، و چند فایل نمونه ارائه دهید.
.Sh "تولید پالت (PALETTE GENERATION)"
.Nm
باید پالت‌ها را از رنگ‌های تصویر ورودی تولید کند، مگر اینکه
.Fl c
استفاده شده باشد؛ در این حالت، از پالت‌های ارائه‌شده استفاده خواهد شد.
.Sy "اگر ترتیب رنگ‌ها در پالت‌ها برای شما اهمیت دارد" ,
برای مثال به این دلیل که می‌خواهید از تعویض پالت (palette swaps) استفاده کنید، لطفاً از
.Fl c
برای مشخص کردن صریح پالت استفاده نمایید.
.Pp
نخست، اگر تصویر حاوی
.Em هرگونه
پیکسل شفاف باشد، رنگ #0 در
.Em تمام
پالت‌ها به آن اختصاص داده می‌شود.
این کار
.Sy حتی در صورت تعیین صریح پالت‌ها با Fl c ;
انجام می‌شود؛ در این حالت، مشخصات ارائه‌شده تنها رنگ #1 به بعد را پوشش می‌دهد.
.Pq اگر این را نمی‌خواهید، از ویرایشگر تصویر خود بخواهید کانال آلفا را حذف کند.
.Pp
پس از تولید پالت‌ها،
.Nm
رنگ‌های درون آن پالت‌ها را با استفاده از قواعد زیر مرتب می‌کند:
.EQ
delim $$
.EN
.Bl -bullet -offset indent
.It
اگر فایل PNG در ساختار داخلی خود حاوی یک پالت باشد (که اغلب یک PNG
.Dq indexed
نامیده می‌شود)، رنگ‌ها در هر پالت خروجی بر اساس ترتیبشان در پالت PNG مرتب خواهند شد.
هر مدخل استفاده‌نشده نادیده گرفته می‌شود و در صورت وجود موارد تکراری، تنها مدخل نخست در نظر گرفته خواهد شد.
.Po اگر می‌خواهید رنگ مشخصی بیش از یک بار ظاهر شود، یا یک رنگ استفاده‌نشده اصلاً حضور داشته باشد، باید در عوض پالت‌ها را صریحاً با
.Fl c
مشخص کنید؛
.Fl c Cm embedded
ممکن است مناسب باشد.
.Pc
.It
در غیر این صورت، اگر PNG تنها حاوی سایه‌های خاکستری باشد، آن‌ها به همان تعدادِ رنگ‌های هر پالت در
.Dq دسته‌ها (bins)
دسته‌بندی می‌شوند و پالت روی این دسته‌ها تنظیم می‌گردد.
تیره‌ترین خاکستری در دسته #0 قرار می‌گیرد و به همین ترتیب ادامه می‌یابد؛ توجه داشته باشید که این برعکس روش RGB در زیر است.
این معادل تعیین پالت DMG به صورت
.Fl c Cm dmg=E4
است. اگر دو رنگ خاکستری متمایز در یک دسته قرار گیرند، در عوض از روش RGB استفاده می‌شود.
.Pp
توجه داشته باشید که
.Nm
درباره آنچه
.Dq خاکستری
می‌داند سخت‌گیر است: مؤلفه‌های قرمز، سبز و آبی هر رنگ باید
.Em همگی
.Em دقیقاً
یکسان باشند.
.It
اگر هیچ‌یک از موارد بالا صدق نکند، رنگ‌ها از روشن‌ترین (نخست) به تیره‌ترین (آخر) مرتب می‌شوند.
تعریفی از درخشندگی (luminance) که
.Nm
به کار می‌برد عبارت است از
.Do
$2126 times red + 7152 times green + 722 times blue$
.Dc .
.El
.EQ
delim off
.EN
.Pp
توجه داشته باشید که رفتار
.Dq indexed
به یک جزئیات داخلی از نحوه ذخیره شدن PNG وابسته است، به ویژه چانک
.Ql PLTE
آن.
از آنجا که ویرایشگرهای تصویر اندکی (مانند GIMP) این جزئیات را در دسترس قرار می‌دهند، این رفتار تنها برای سازگاری حفظ شده است و باید منسوخ‌شده در نظر گرفته شود.
.Pp
مشخص شده است که تولید پالت یک مسئله NP-کامل موسوم به «صفحه‌بندی» (pagination) است، بنابراین
.Nm
تلاشی برای یافتن راه‌حل بهینه نمی‌کند، بلکه در عوض از یک روش اکتشافی (heuristic) موسوم به "overload-and-remove" برای یافتن یک پاسخ مناسب در مدت زمانی معقول استفاده می‌کند.
(به جز محدودیت‌های مستندشده در بالا، هیچ تضمینی درباره چگونگی تولید پالت‌ها توسط این الگوریتم وجود ندارد.)
امکان محاسبه راه‌حل بهینه به صورت بیرونی (برای مثال با استفاده از یک solver) وجود دارد، که سپس می‌توان آن را از طریق
.Fl c
به
.Nm
ارائه داد..Sh "فایل‌های خروجی (OUTPUT FILES)"
تمام فایل‌های خروجی توسط
.Nm
فایل‌های باینری هستند و به‌گونه‌ای طراحی شده‌اند که از قالب‌های بومی Game Boy و Game Boy Color پیروی کنند.
آنچه در ادامه می‌آید توصیف کوتاهی از این قالب‌ها شامل جزئیات اختصاصی
.Nm
است.
برای توصیف‌های کامل‌تر، مناسب افراد مبتدی و همراه با تصویرسازی از قالب‌های بومی، لطفاً
.Lk https://gbdev.io/pandocs/Graphics Pan Docs
را بررسی کنید.
.Ss "داده‌های کاشی (Tile data)"
داده‌های کاشی مانند یک دامپ باینری از VRAM، بدون هیچ‌گونه فاصله‌گذاری (padding) بین کاشی‌ها خروجی داده می‌شوند.
هر کاشی ۱۶ بایت است، ۲ بایت در هر سطر از ۸ پیکسل؛ بیت‌های شناسه‌های رنگ در هر بایت
.Pq یا Dq bitplane
تقسیم می‌شوند.
شناسهٔ رنگ چپ‌ترین پیکسل در پرارزش‌ترین بیت‌های این دو بایت، و شناسهٔ رنگ راست‌ترین پیکسل در کم‌ارزش‌ترین بیت‌های آن‌ها ذخیره می‌شود.
.Pp
هنگامی که عمق بیت
.Pq Fl d
روی ۱ تنظیم شود، پرارزش‌ترین bitplane (بایت دوم) هر سطر، از آنجا که همگی صفر است، در خروجی نوشته نمی‌شود.
.Ss "داده‌های پالت (Palette data)"
داده‌های پالت مانند یک دامپ از حافظهٔ پالت خروجی داده می‌شوند.
هر رنگ به‌صورت RGB555 لیتل-اندین (little-endian) بومی GBC نوشته می‌شود که بیت ۱۵ بی‌استفادهٔ آن روی ۰ تنظیم شده است.
هیچ فاصله‌گذاری (padding) بین رنگ‌ها و پالت‌ها وجود ندارد؛ با این حال، رنگ‌های خالی در پالت‌ها به‌صورت 0xFFFF خروجی داده می‌شوند.
.EQ
delim $$
.EN
برای نمونه، اگر ۵ پالت با
.Fl s Cm 4
تولید شوند، اندازهٔ فایل داده‌های پالت $2 times 4 times 5 = 40$ بایت خواهد بود، حتی اگر برخی پالت‌ها شامل کمتر از ۳ رنگ باشند.
.EQ
delim off
.EN
توجه داشته باشید که
.Fl n
تنها سقف تعداد پالت‌های تولیدی (و در نتیجه اندازهٔ این فایل) را تعیین می‌کند، اما ممکن است همچنان پالت‌های کمتری تولید شود.
.Ss "داده‌های نگاشت کاشی (Tile map data)"
یک نگاشت کاشی (tile map) آرایه‌ای از شناسه‌های کاشی است، با یک بایت برای هر شناسهٔ کاشی.
نخستین بایت همواره متناظر با شناسهٔ کاشی در گوشهٔ بالا-چپ تصویر ورودی است؛ دومین بایت یا شناسهٔ کاشی سمت راست آن است (به‌طور پیش‌فرض)، یا کاشی زیرین آن
.Pq با Fl Z Ns
؛ و به همین ترتیب در همان جهت ادامه می‌یابد.
سطرها / ستون‌ها (به ترتیب) به‌صورت متوالی و بدون هیچ فاصله‌گذاری (padding) ذخیره می‌شوند.
.Ss "داده‌های نگاشت صفت (Attribute map data)"
نگاشت‌های صفت، مشابه GBC، از ساختار نگاشت‌های کاشی پیروی می‌کنند، به‌ویژه در ترتیبی که بایت‌ها خروجی داده می‌شوند.
محتوای هر بایت از قالب بومی GBC پیروی می‌کند:
.Bl -column "بیت ۲\(en۰" "شماره پالت پس‌زمینه (BGP)"
.It بیت ۷ Ta اولویت BG-to-OAM Ta تنظیم روی 0
.It بیت ۶ Ta وارونگی عمودی (Vertical Flip) Ta 0=عادی، 1=آینه‌ای عمودی
.It بیت ۵ Ta وارونگی افقی (Horizontal Flip) Ta 0=عادی، 1=آینه‌ای افقی
.It بیت ۴ Ta استفاده‌نشده Ta تنظیم روی 0
.It بیت ۳ Ta شماره بانک VRAM کاشی Ta 0=Bank 0, 1=Bank 1
.It بیت ۲\(en۰ Ta شماره پالت پس‌زمینه Ta BGP0-7
.El
.Pp
توجه داشته باشید که اگر بیش از ۸ پالت استفاده شود، تنها ۳ بیت کم‌ارزش شناسهٔ پالت در خروجی نوشته می‌شود.
.Ss "مسیرهای خروجی خودکار (Automatic output paths)"
برای راحتی،
.Nm
میانبرهایی را برای تولید همهٔ فایل‌ها در همان دایرکتوری فراهم می‌کند.
این کار با استفاده از نسخهٔ بزرگ‌نویسی‌شدهٔ یک پرچم انجام می‌شود
.Pq برای نمونه، Fl A No به جای Fl a .
مسیر
.Ar base_path
همان مسیر تصویر ورودی است
.Pq یا اگر Fl O No داده شده باشد، مسیر خروجی داده‌های کاشی از Fl o
که پسوند آن، در صورت وجود، حذف شده است.
.Pp
برای نمونه، این دو دستور معادل یکدیگر هستند:
.Bd -literal -offset indent
$ rgbgfx img/player.png -o build/player.2bpp -P
$ rgbgfx img/player.png -o build/player.2bpp -p img/player.pal
.Ed
.Pp
و این دو دستور نیز معادلند:
.Bd -literal -offset indent
$ rgbgfx img/player.png -o build/player.2bpp -O -P
$ rgbgfx img/player.png -o build/player.2bpp -p build/player.pal
.Ed
.Sh "حالت معکوس (REVERSE MODE)"
.Nm
می‌تواند از داده‌های معتبر یک تصویر PNG تولید کند.
این قابلیت ممکن است برای استخراج گرافیک‌ها (ripping)، بازیابی تصاویر اصلیِ گم‌شده و غیره مفید باشد.
با این حال، یک نکتهٔ مهم در مورد مورد آخر وجود دارد: فرایند تبدیل در هر دو جهت
.Sy اتلافی (lossy)
است، بنابراین تصویر
.Do معکوس‌شده Dc
کاملاً با تصویر اصلی یکسان نخواهد بود\(emاما به خروجی Game Boy نزدیک خواهد بود.
.Pq به یاد داشته باشید که بسیاری از کنسول‌ها رنگ‌های متفاوتی در خروجی تولید می‌کنند، بنابراین هیچ رندر مرجع واقعی وجود ندارد .
.Pp
هنگام استفاده از حالت معکوس، اطمینان حاصل کنید همان پرچم‌هایی را ارسال می‌کنید که هنگام تولید داده‌ها استفاده شده بودند، به‌ویژه
.Fl C , d , N , s , x ,
و
.Fl Z .
بخش
.Do Sx At-files Dc
ممکن است در این زمینه کمک کند.
.Nm
در مورد هرگونه ناسازگاری که شناسایی کند هشدار خواهد داد.
.Pp
فایل‌هایی که در حالت عادی خروجی هستند
.Pq Fl a , p , t
به ورودی تبدیل می‌شوند، و در
.Ar file
به جای خواندن، نوشته خواهد شد، بنابراین نیازی نیست از قبل وجود داشته باشد.
هر یک از این ورودی‌ها که ارسال نشوند، روی مقادیر پیش‌فرض فرض می‌شوند:
.Bl -column "داده‌های کاشی (tile data)"
.It پالت‌ها (palettes) Ta داده‌های پالتِ نامشخص باعث می‌شود
.Nm
حالت DMG (Game Boy تک‌رنگ) را فرض کند: یک پالت منفرد از ۴ رنگ خاکستری.
امکان ارسال پالت‌ها با استفاده از
.Fl c
به جای
.Fl p
نیز وجود دارد.
.It داده‌های کاشی (tile data) Ta داده‌های کاشی حتماً باید ارائه شوند، چرا که هیچ فرض معقولی برای جایگزینی وجود ندارد.
.It نگاشت کاشی (tile map) Ta نبودِ نگاشت کاشی باعث می‌شود
.Nm
فرض کند کاشی‌ها یکتا نشده‌اند، و باید به همان ترتیبی که ذخیره شده‌اند چیده شوند.
.It نگاشت صفت (attribute map) Ta بدون یک نگاشت صفت،
.Nm
فرض می‌کند که هیچ کاشی‌ای وارون (آینه‌ای) نشده است.
.El.Sh "عیب‌یابی (DIAGNOSTICS)"
هشدارها پیام‌های عیب‌یابی هستند که رفتارهای احتمالاً نادرست را نشان می‌دهند، رفتارهایی که لزوماً فرایند تبدیل را دچار اختلال نمی‌کنند.
گزینه‌های زیر نحوهٔ پردازش هشدارها را تغییر می‌دهند.
.Bl -tag -width Ds
.It Fl Werror
تمام هشدارها را به خطا تبدیل می‌کند.
این گزینه را می‌توان با
.Fl Wno-error
نفی کرد تا از تبدیل همهٔ هشدارها به خطا جلوگیری شود.
.It Fl Werror=
هشدار یا فراهشدار (meta warning) مشخص‌شده را به خطا تبدیل می‌کند.
نام هشدار در ادامه اضافه می‌شود
.Pq برای مثال: Fl Werror=obsolete ,
و این هشدار به‌طور ضمنی فعال شده و به خطا تبدیل می‌گردد.
این گزینه را می‌توان با
.Fl Wno-error=
نفی کرد تا از تبدیل یک هشدار مشخص‌شده به خطا جلوگیری شود، حتی اگر
.Fl Werror
اعمال شده باشد.
.El
.Pp
هشدارهای زیر هشدارهای
.Dq meta
هستند که مجموعه‌ای از هشدارهای دیگر را فعال می‌کنند.
اگر یک هشدار خاص هم از طریق یک پرچم متا و هم از طریق یک پرچم خاص تغییر وضعیت دهد، پرچم خاص‌تر اولویت دارد.
موقعیت در خط فرمان به‌عنوان عامل تعیین‌کننده عمل می‌کند و آخرین مورد اعمال می‌شود.
.Bl -tag -width Ds
.It Fl Wall
هشدارهایی را فعال می‌کند که احتمالاً نشان‌دهندهٔ یک خطا یا رفتار ناخواسته هستند و به‌راحتی می‌توان آن‌ها را برطرف کرد.
.It Fl Weverything
به‌معنای واقعی کلمه تمام هشدارها را فعال می‌کند.
.El
.Pp
هشدارهای زیر پرچم‌های واقعی هشدار هستند؛ همراه با هر شرح، پرچم هشدار مربوطه آورده شده است.
توجه داشته باشید که هر یک از این پرچم‌ها حالت نفی نیز دارند (برای مثال،
.Fl Wobsolete
هشداری را فعال می‌کند که
.Fl Wno-obsolete
غیرفعال می‌کند؛ و
.Fl Wall
تمام هشدارهایی را که
.Fl Wno-all
غیرفعال می‌کند، فعال می‌سازد).
تنها پرچم غیرپیش‌فرض در اینجا فهرست شده است.
صرف‌نظر از پیشوند
.Dq no-
، مدخل‌ها به‌ترتیب حروف الفبا فهرست شده‌اند.
.Bl -tag -width Ds
.It Fl Wembedded
زمانی هشدار می‌دهد که یک پالت تولیدشده بر اساس پالت تعبیه‌شده در PNG ورودی مرتب شده باشد، اما
.Fl c Cm embedded
مشخص نشده باشد.
این هشدار توسط
.Fl Weverything
فعال می‌شود.
.It Fl Wno-obsolete
هنگام مواجهه با قابلیت‌های منسوخی که از رده خارج شده‌اند و ممکن است در آینده حذف شوند، هشدار می‌دهد.
.It Fl Wtrim-nonempty
زمانی هشدار می‌دهد که
.Fl x
یک تایل غیرخالی را برش دهد.
یک تایل «خالی» به‌طور کامل از رنگ ۰ پالت خود استفاده می‌کند.
این هشدار توسط
.Fl Wall
فعال می‌شود.
.El
.Sh "مثال‌ها (EXAMPLES)"
دستور زیر فقط تصویر
.Ql tileset.png
را اعتبارسنجی می‌کند (بررسی اندازهٔ آن، اینکه همهٔ تایل‌ها تعداد رنگ مناسبی داشته باشند و غیره)، اما چیزی در خروجی تولید نمی‌کند:
.Pp
.Dl $ rgbgfx src/res/maps/overworld/tileset.png
.Pp
دستور زیر تصویر
.Ql tileset.png
را تنها با استفاده از دو پالت ارائه‌شده تبدیل می‌کند و داده‌های تایل 2bpp تولیدشده را در
.Ql tileset.2bpp ,
و نقشهٔ ویژگی‌ها را در
.Ql tileset.attrmap
ذخیره خواهد کرد.
.Pp
.Dl $ rgbgfx -c '#ffffff,#8d05de, #dc7905,#000000 ; #fff,#8d05de, #7e0000 \&, #000' -A -o tileset.2bpp tileset.png
.Pp
دستور زیر تایل‌های تکراری تصویر
.Ql title_screen.png
را حذف کرده (تنها یک نسخه از هر تایل یکتا را نگه می‌دارد)، داده‌های تایل 2bpp تولیدشده را در
.Ql title_screen.2bpp ,
و نقشهٔ تایل را در
.Ql title_screen.tilemap
ذخیره می‌کند.
.Pp
.Dl $ rgbgfx -u title_screen.png -o title_screen.2bpp -t title_screen.tilemap
.Pp
دستور زیر مشخصات پالت درون‌خطی ارائه‌شده را به یک مجموعه پالت تبدیل کرده و مجموعه پالت را بدون نیاز به تصویر ورودی در
.Ql colors.pal ,
ذخیره می‌کند.
.Pp
.Dl $ rgbgfx -c '#fff,#ff0,#f80,#000' -p colors.pal
.Pp
دستورهای زیر دو تصویر مرحله را با استفاده از یک مجموعه‌تایل یکسان تبدیل می‌کنند و در صورتی که هر یک از آن‌ها حاوی تایل‌هایی باشد که در مجموعه‌تایل نیست، با خطا متوقف می‌شوند.
.Pp
.Bd -literal -offset Ds
$ 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
.Ed.Sh "گزارش باگ‌ها (BUGS)"
لطفاً باگ‌ها یا اشتباهات موجود در این مستندات را در
.Lk https://github.com/gbdev/rgbds/issues GitHub
گزارش کنید.
.Sh "همچنین ببینید (SEE ALSO)"
.Xr rgbasm 1 ,
.Xr rgblink 1 ,
.Xr rgbfix 1 ,
.Xr rgbds 7
.Pp
مرجع سخت‌افزار Game Boy
.Lk https://gbdev.io/pandocs/Graphics Pan Docs ,
به‌ویژه بخش مربوط به گرافیک.
.Sh "تاریخچه (HISTORY)"
.Nm
در ابتدا توسط stag019 به‌عنوان برنامه‌ای برای بسته‌بندی در RGBDS نوشته شد.
این برنامه بعداً توسط
.An ISSOtm
بازنویسی شد و در حال حاضر توسط شماری از مشارکت‌کنندگان در
.Lk https://github.com/gbdev/rgbds
نگه‌داری می‌شود.