`GLSLC`(1)   `GLSLC`(1)

`glslc` - کامپایلر خط فرمانی GLSL/HLSL به SPIR-V با آرگومان‌های سازگار با Clang

glslc [--help]
glslc [-h]
glslc [--show-limits]
glslc [-c|-S|-E]
      [-x ...] [-std=standard]
      [ ... options for resource bindings ... ]
      [-fhlsl-16bit-types]
      [-fhlsl-offsets]
      [-fhlsl-functionality1]
      [-fentry-point=<name>]
      [-fauto-map-locations]
      [-finvert-y]
      [-flimit=...]
      [-flimit-file <resource-limits-file>]
      [-fshader-stage=...]
      [--target-env=...]
      [--target-spv=...]
      [-g]
      [-O0|-Os]
      [-Idirectory...]
      [-Dmacroname[=value]...]
      [-w] [-Werror]
      [-o outfile]
      shader...

دستور glslc هر دو نوع فایل‌های منبع GLSL/HLSL و فایل‌های اسمبلی SPIR-V را به عنوان ورودی می‌پذیرد.

دستور glslc سه روش برای تعیین مرحلهٔ سایه‌زنِ یک فایل منبع GLSL ارائه می‌دهد: -fshader-stage=<stage>، #pragma shader_stage(<stage>) و پسوند فایل. گزینهٔ -fshader-stage= اولویت بالاتری نسبت به #pragma shader_stage() دارد، و این دستور نیز اولویت بالاتری نسبت به پسوند فایل دارد.

مراحل سایه‌زن را می‌توان با نام‌گذاری فایل با یک پسوند مناسب همان‌طور که در جدول زیر نشان داده شده است، مشخص کرد. از سوی دیگر، -fshader-stage= و #pragma shader_stage() به شما امکان می‌دهند مراحل سایه‌زن را از خط فرمان و درون فایل منبع تعیین کنید. مقادیر ممکن برای stage نیز در جدول زیر فهرست شده‌اند. جزئیات مربوط به -fshader-stage= را می‌توانید در بخش اختصاصی خودش پیدا کنید.

جدول ۱. انتخاب مرحلهٔ سایه‌زن (Shader Stage Selection)

مرحلهٔ سایه‌زن (Shader Stage) پسوند فایل سایه‌زن <stage>
رأس (vertex) .vert vertex
قطعه (fragment) .frag fragment
کنترل تسلیشن (tesselation control) .tesc tesscontrol
ارزیابی تسلیشن (tesselation evaluation) .tese tesseval
هندسه (geometry) .geom geometry
محاسباتی (compute) .comp compute

دستور #pragma shader_stage() به دستور پیش‌پردازندهٔ #pragma وابسته است؛ بنابراین، نشانهٔ (token) درون shader_stage() مشمول گسترش ماکروهای پیش‌پردازنده نمی‌شود. این مقدار باید دقیقاً یکی از مقادیر stage در جدول بالا باشد.

دستور #pragma shader_stage() به شرح زیر عمل می‌کند:

•نخستین دستور #pragma shader_stage() در یک واحد ترجمه (translation unit) باید پیش از هر نشانهٔ غیر پیش‌پردازنده‌ای قرار گیرد.
•اگر بیش از یک دستورالعمل #pragma shader_stage() در همان واحد ترجمه وجود داشته باشد، تمام stageهای مشخص‌شده باید یکسان باشند. در غیر این صورت، glslc خطایی صادر خواهد کرد.

فایل‌های ورودی اسمبلی SPIR-V باید از نحو https://github.com/KhronosGroup/SPIRV-Tools/blob/master/syntax.md تعریف‌شده در پروژهٔ SPIRV-Tools https://github.com/KhronosGroup/SPIRV-Tools پیروی کنند و دارای پسوند .spvasm باشند. گزینه‌های خط فرمان با فایل‌های اسمبلی SPIR-V رفتار متفاوتی دارند؛ برخی ممکن است آن‌ها را نادیده بگیرند، مانند -E و -S، و برخی حتی ممکن است با آن‌ها نه به‌عنوان فایل‌های اسمبلی SPIR-V رفتار کنند، مانند -fshader-stage=.

اگر نامی از طریق -o مشخص شده باشد، به فایل خروجی همان نام داده خواهد شد. در غیر این صورت،

•اگر یکی از گزینه‌های انتخاب مرحلهٔ کامپایل مشخص شده باشد (-S یا -c)، به‌ازای هر فایل شیدر ورودی، یک فایل خروجی تولید خواهد شد. فایل خروجی تولیدشده با پسوندی متناسب با مرحلهٔ کامپایل خاتمه می‌یابد که برابر با .spvasm برای -S و .spv برای -c است. این نام به نام و پسوند فایل اصلی بستگی خواهد داشت.
•اگر فایل ورودی پسوندِ انتخاب مرحلهٔ شیدر داشته باشد، نام فایل خروجی با افزودن پسوند مرحلهٔ کامپایل به انتهای نام فایل ورودی تعیین می‌شود؛ به‌عنوان مثال، glslc -c foo.vert فایل foo.vert.spv را تولید می‌کند و glslc -S bar.frag فایل bar.frag.spvasm را تولید خواهد کرد.
•در غیر این صورت، نام فایل خروجی با جایگزین کردن پسوند فایل ورودی (در صورت وجود) با پسوند مرحلهٔ کامپایل مشخص خواهد شد؛ به‌عنوان مثال، glslc -c foo فایل foo.spv را تولید می‌کند و glslc -S bar.glsl فایل bar.spvasm را تولید خواهد کرد.
•اگر هیچ مرحله‌ای از کامپایل انتخاب نشده باشد، نام فایل خروجی a.spv خواهد بود.

گزینهٔ --help یا -h به کامپایلر glslc اعلام می‌کند که تمام گزینه‌های موجود را نمایش دهد و خارج شود.

--show-limits محدودیت‌های پیش‌فرض منابع را برای کامپایل شیدر نمایش می‌دهد. نحو آن مشابه ساختار پذیرفته‌شده توسط -flimit= و محتویات فایل مشخص‌شده توسط -flimit-file است.

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

خروجی position.Y را در یک شیدر رأس (vertex shader) معکوس می‌کند.

-flimit=<resource-limits> امکان تعیین محدودیت‌های منابع را فراهم می‌کند. آرگومان باید دنباله‌ای از جفت‌های نام محدودیت و مقدار عدد صحیح باشد. نشانه‌ها (tokens) باید با فاصله سفید (whitespace) جدا شوند. اگر یک محدودیت چند بار مشخص شود، تنها مقدار آخر اِعمال خواهد شد.

از --show-limits برای نمایش مقادیر پیش‌فرض و نمونهٔ نحو استفاده کنید.

این گزینه بر تمام شیدرهای کامپایل‌شده اثر می‌گذارد.

-flimit-file <resource-limits-file> امکان تعیین محدودیت‌های منابع را در یک فایل فراهم می‌کند. نحو محتویات فایل مشابه آرگومان -flimit= و خروجی --show-limits است. این گزینه فایل‌های پیکربندی منابع Glslang، مثلاً فایل تولیدشده با glslangValidator -c، را می‌پذیرد.

این گزینه بر تمام شیدرهای کامپایل‌شده اثر می‌گذارد.

-fshader-stage=<stage> امکان تعیین مرحله شیدر (shader stage) را برای یک یا چند ورودی از طریق خط فرمان فراهم می‌کند.

مقادیر ممکن برای <stage> در جدول «انتخاب مرحله شیدر» فهرست شده‌اند.

-fshader-stage= به شرح زیر عمل می‌کند:

•-fshader-stage= مرحله شیدر را برای فایل‌های ورودی پس از خود تعیین می‌کند. این گزینه بر مرحلهٔ هیچ‌یک از ورودی‌های پیشین در خط فرمان اثر ندارد.
•هنگام ارائهٔ بیش از یک آرگومان -fshader-stage=، نزدیک‌ترین آرگومان ماقبلِ یک فایل ورودی اِعمال می‌شود.
•فایل شیدری که با پسوندهای شناخته‌شده فایل‌های شیدر پایان نمی‌یابد، باید یک آرگومان -fshader-stage= قبل از خود داشته باشد تا مرحلهٔ آن مشخص گردد.
•اگر یک -fshader-stage= پیش از فایلی قرار گیرد که حاوی دستورالعمل #pragma shader_stage() است، دستورالعمل نادیده گرفته شده و در عوض آرگومان -fshader-stage= استفاده می‌شود.
•اگر یک -fshader-stage= پیش از فایلی با پسوند شناخته‌شدهٔ شیدر قرار گیرد، پسوند فایل نادیده گرفته شده و در عوض آرگومان -fshader-stage= استفاده می‌شود.

هشدار

گزینهٔ -fshader-stage= پسوند فایل را بازنویسی (override) می‌کند؛ این بدان معناست که
نباید همراه با فایل‌های اسمبلی SPIR-V استفاده شود زیرا glslc فایل‌های اسمبلی SPIR-V ارائه‌شده را به عنوان کد منبع GLSL در مرحلهٔ شیدر مشخص‌شده در نظر می‌گیرد. اگر نیاز به ارائهٔ هم‌زمان فایل‌های اسمبلی SPIR-V و -fshader-stage= در همان خط فرمان دارید، لطفاً فایل‌های اسمبلی SPIR-V را پیش از نخستین -fshader-stage= قرار دهید، زیرا -fshader-stage= فقط بر رفتار پردازش فایل‌های پس از خود اثر می‌گذارد.

-std=<value> به شما امکان می‌دهد نسخه و نمایهٔ (profile) شیدر را در خط فرمان مشخص کنید. <value> می‌تواند هر ترکیب معتبری از شماره نسخه و نمایهٔ GLSL باشد، مانند 310es، 450core و غیره. نمایه را می‌توان طبق قوانین GLSL حذف کرد، مانند 450.

-std= به شرح زیر عمل می‌کند:

•-std= بر نسخهٔ تمام ورودی‌های GLSL ارائه‌شده به glslc تأثیر می‌گذارد.
•-std= برای ورودی‌های HLSL نادیده گرفته می‌شود.
•-std= دستورالعمل‌های #version را در تمام شیدرهای ورودی، از جمله مواردی که قبل از این آرگومان قرار دارند، بازنویسی می‌کند.
•اگر یک آرگومان -std= نسخه‌ای متفاوت از دستورالعمل #version در یک فایل ورودی را مشخص کند، glslc یک هشدار صادر خواهد کرد.
•اگر چندین آرگومان -std= در خط فرمان مشخص شده باشند، تنها آخرین مورد اعمال خواهد شد.

احتیاط

-std= بر دستورالعمل #version در خروجی پیش‌پردازش‌شده تأثیری
نمی‌گذارد. بدین معنا که وقتی -std= نسخه‌ای متفاوت از کد منبع شیدر را مشخص کند، دستورالعمل #version در خروجی پیش‌پردازش‌شده همچنان همان مقدار موجود در کد منبع خواهد بود. اما -std= بر رفتار دستورالعمل‌های #line در خروجی پیش‌پردازش‌شده تأثیر می‌گذارد. رفتار دستورالعمل‌های #line از نسخهٔ مشخص‌شده توسط -std= پیروی خواهد کرد.

گزینهٔ --target-env=<value> به شما امکان می‌دهد یک محیط هدف را در خط فرمان مشخص کنید. این گزینه بر تولید هشدارها و خطاها اثر می‌گذارد. مقدار <value> می‌تواند یکی از موارد زیر باشد:

•vulkan: ایجاد SPIR-V تحت معناشناسی Vulkan 1.0.
•vulkan1.0: ایجاد SPIR-V تحت معناشناسی Vulkan 1.0.
•vulkan1.1: ایجاد SPIR-V تحت معناشناسی Vulkan 1.1.
•vulkan1.2: ایجاد SPIR-V تحت معناشناسی Vulkan 1.2.
•vulkan1.3: ایجاد SPIR-V تحت معناشناسی Vulkan 1.3.
•vulkan1.4: ایجاد SPIR-V تحت معناشناسی Vulkan 1.4.
•opengl: ایجاد SPIR-V تحت معناشناسی OpenGL 4.5.
•opengl4.5: ایجاد SPIR-V تحت معناشناسی OpenGL 4.5.

کد تولیدشده از SPIR-V 1.0 استفاده می‌کند، مگر کدهای کامپایل‌شده برای Vulkan 1.1 که از SPIR-V 1.3، و کدهای کامپایل‌شده برای Vulkan 1.2 که از SPIR-V 1.5 استفاده می‌کنند.

اگر این گزینه مشخص نشود، مقدار پیش‌فرض vulkan1.0 به کار می‌رود.

نکته: پشتیبانی از نمایه سازگاری OpenGL، opengl_compat، حذف شده است..SS "--target-spv="

--target-spv=<value> به شما امکان می‌دهد نسخه SPIR-V مورد استفاده در ماژول تولیدشده را مشخص کنید. حالت پیش‌فرض، استفاده از بالاترین نسخه SPIR-V است که پشتیبانی از آن توسط محیط هدف الزامی می‌باشد. پیش‌فرض‌ها برای محیط‌های هدف خاص Vulkan به شرح زیر است: SPIR-V 1.0 برای Vulkan 1.0، SPIR-V 1.3 برای Vulkan 1.1، و SPIR-V 1.5 برای Vulkan 1.2.

مقدار <value> می‌تواند یکی از موارد زیر باشد:

•spv1.0
•spv1.1
•spv1.2
•spv1.3
•spv1.4
•spv1.5
•spv1.6

گزینه -x به شما امکان می‌دهد زبان فایل‌های سایه‌زن ورودی را مشخص کنید. زبان‌های معتبر glsl و hlsl هستند. اگر پسوند فایل hlsl باشد، زبان پیش‌فرض HLSL است؛ در غیر این صورت پیش‌فرض 'glsl' خواهد بود.

نکته: در کامپایل HLSL، از قواعد بسته‌بندی (آفست) HLSL برای متغیرهایی که خروجی سایه‌زن رأس (vertex shader)، و ورودی‌ها و خروجی‌های هر دو سایه‌زن هندسه (geometry shader) و سایه‌زن پیکسل (pixel shader) هستند استفاده خواهد شد.

گزینه -c به کامپایلر glslc اعلام می‌کند که مراحل پیش‌پردازش و کامپایل را اجرا کند. هر فایل سایه‌زن ورودی به یک فایل باینری SPIR-V منجر می‌شود؛ نام‌گذاری این فایل‌های باینری SPIR-V طبق قواعد بخش Output File Naming انجام می‌گیرد.

گزینه -E به کامپایلر glslc اعلام می‌کند که فقط مرحله پیش‌پردازش را اجرا کند. این گزینه بر -c و -S اولویت دارد و آن‌ها را لغو می‌کند. خروجی پیش‌پردازش‌شده در خروجی استاندارد نوشته می‌شود، در حالی که خطاهای پیش‌پردازش در خطای استاندارد نوشته خواهند شد. اگر چندین فایل سایه‌زن ورودی مشخص شده باشد، خروجی پیش‌پردازش‌شده همه آن‌ها به ترتیبی که در خط فرمان تعیین شده، در خروجی استاندارد نوشته می‌شود.

با این گزینه، glslc هیچ عملیاتی روی فایل‌های اسمبلی SPIR-V انجام نخواهد داد.

گزینه -S به کامپایلر glslc اعلام می‌کند که مرحله پیش‌پردازش، کامپایل و سپس دی‌اسمبل (disassembling) را اجرا کند. این گزینه بر -c اولویت دارد و آن را لغو می‌کند. هر فایل سایه‌زن ورودی به یک فایل اسمبلی SPIR-V منجر می‌شود؛ نام‌گذاری این فایل‌های اسمبلی SPIR-V طبق قواعد بخش Output File Naming انجام می‌گیرد.

با این گزینه، glslc هیچ عملیاتی روی فایل‌های اسمبلی SPIR-V انجام نخواهد داد.

اگر هیچ‌یک از گزینه‌های بالا مشخص نشود، کامپایلر glslc مراحل پیش‌پردازش، کامپایل و پیوند دادن (linking) را اجرا خواهد کرد.


هشدار

پیوند دادن (Linking) چندین فایل سایه‌زن ورودی در حال حاضر پشتیبانی نمی‌شود.

گزینه -Dmacroname[=[value]] به شما اجازه می‌دهد پیش از پیش‌پردازش فایل‌های سایه‌زن ورودی، یک ماکروی پیش‌پردازنده تعریف کنید. اگر value حذف شود، ماکرو با مقداری خالی تعریف می‌شود.

گزینه -Idirectory یا -I directory دایرکتوری مشخص‌شده را به مسیر جستجو برای فایل‌های include اضافه می‌کند. دایرکتوری می‌تواند یک مسیر مطلق یا یک مسیر نسبی به دایرکتوری کاری فعلی باشد.

درخواست می‌کند که کامپایلر اطلاعات اشکال‌زدایی (debug) در سطح کد منبع، مانند نام شناسه‌ها و شماره خطوط را در کد شیء قرار دهد.

این گزینه مانع از فعال‌سازی مرحله بهینه‌سازی strip-debug-info توسط گزینه -O می‌شود.


نکته

در حال حاضر این گزینه هیچ اثری ندارد. عملکرد کامل آن وابسته به پشتیبانی
glslang از تولید اطلاعات اشکال‌زدایی است.

-O مشخص می‌کند که از کدام سطح بهینه‌سازی استفاده شود:

•-O0 به معنای «بدون بهینه‌سازی» است. این سطح کدی با بیشترین قابلیت اشکال‌زدایی تولید می‌کند.
•-O به معنای سطح بهینه‌سازی پیش‌فرض برای عملکرد بهتر است.
•-Os بهینه‌سازی‌ها را جهت کاهش حجم کد فعال می‌کند.

-mfmt=<format> قالب خروجی را برای خروجی کامپایل در قالب کد باینری SPIR-V انتخاب می‌کند. گزینه‌های پشتیبانی‌شده در جدول گزینه‌های قالب خروجی باینری فهرست شده‌اند. استفاده از این گزینه تنها زمانی معتبر است که خروجی کامپایل، کد باینری SPIR-V باشد. مشخص کردن هر یک از گزینه‌های فهرست‌شده در زیر هنگامی که خروجی کد باینری SPIR-V نباشد، مانند دیس‌اسمبلی (با مشخص کردن -S) یا متنی (با مشخص کردن -M، -MM یا -E)، موجب بروز خطا خواهد شد.

جدول ۲. گزینه‌های قالب خروجی باینری

گزینه قالب توضیحات
bin خروجی دادن کد باینری SPIR-V به صورت دنباله‌ای از کلمات باینری ۳۲-بیتی با ترتیب بایت بومی میزبان (host native endianness). این قالب پیش‌فرض برای خروجی کامپایل باینری SPIR-V است.
num خروجی دادن کد باینری SPIR-V به عنوان یک فایل متنی شامل فهرستی از اعداد هگزادسیمال جداشده با کاما. مثال: glslc -c -mfmt=num main.vert -o output_file.txt محتوای output_file.txt: 0x07230203,0x00010000,0x00080001,0x00000006...
c خروجی دادن کد باینری SPIR-V به عنوان یک فایل متنی حاوی فهرست مقداردهی اولیه به سبک C (C-style initializer list). این گزینه صرفاً خروجی گزینه num را درون آکولاد قرار می‌دهد. مثال: glslc -c -mfmt=c main.vert -o output_file.txt محتوای output_file.txt: {0x07230203, 0x00010000, 0x00080001, 0x00000006...}

انواع ۱۶بیتی را برای کامپایل HLSL فعال می‌کند.

هنگام تعیین آفست‌های اعضای بلوک‌ها، به جای قوانین GLSL از قوانین بسته‌بندی HLSL استفاده می‌کند. این گزینه هنگام کامپایل برای HLSL همیشه فعال است.

افزونهٔ SPV_GOOGLE_hlsl_functionality1 را فعال کرده و به کامپایلر دستور می‌دهد تا:

•تزئینات رشته‌ای معنایی HLSL را روی اشیاء رابط نشانه‌گذاری کند
•ارتباط یک منبع UAV با بافر شمارندهٔ همراه آن را به‌طور صریح ثبت کند.

این گزینه را می‌توان با خط زیرین نیز نوشت: -fhlsl_functionality1.

گزینهٔ -fentry-point=<name> امکان تعیین نام نقطهٔ ورود را فراهم می‌کند. این گزینه تنها برای کامپایل HLSL معنادار است. مقدار پیش‌فرض "main" است.

برای کامپایل GLSL، گزینهٔ -fauto-map-locations به کامپایلر دستور می‌دهد تا در صورت عدم تعیین صریح در مبدأ سایه‌زن، شماره‌های مکان را به‌طور خودکار به متغیرهای ورودی و خروجی مرحله که توسط کاربر تعریف شده‌اند اختصاص دهد.

برای کامپایل HLSL، این گزینه به‌طور پیش‌فرض فعال است.

رابط‌های برنامه‌نویسی کلاینت (Client APIs) معمولاً به توافق مراحل مجاور روی رابط I/O خود نیاز دارند. کامپایلر در هر لحظه تنها یک مرحله را می‌بیند، بنابراین اکیداً توصیه می‌شود که از تکیه بر این گزینه برای تخصیص مکان‌ها خودداری کنید.

در عوض، باید یک شمارهٔ اتصال (binding) صریح در مبدأ سایه‌زن به شرح زیر مشخص شود:

•در یک سایه‌زن GLSL، از یک مشخصهٔ چینش location استفاده کنید:
layout(location = 1) in vec4 x;
•در یک سایه‌زن HLSL، از یک صفت vk::location استفاده کنید:
[[vk::location(1)]] float4 FooShader(
  [[vk::location(0)]] float4 a,
  [[vk::location(2)]] float4 b) : COLOR0 {
  return a + b;
}

[[option-fpreserve-bindings ==== -fpreserve-bindings

بهینه‌ساز را موظف می‌کند اعلان‌های اتصالات (bindings) را حفظ کند، حتی زمانی که مشخص باشد از آن اتصالات استفاده نمی‌شود..SS "گزینه‌های هشدار و خطا (Warning and Error Options)"

-w تمام خروجی‌های هشدار glslc را فرونشانی می‌کند. هر هشداری که ممکن بود تولید شود، در سکوت نادیده گرفته می‌شود.

-Werror باعث می‌شود در glslc با هر هشداری همانند یک خطا رفتار شود. این بدان معناست که تمام پیام‌های warning: به‌صورت error: نشان داده می‌شوند و هرگونه هشداری موجب ایجاد یک کد خروج غیرصفر از سوی glslc خواهد شد. اگر -w مشخص شده باشد، هشدارهای تولیدشده پیش از تبدیل به خطا فرونشانی می‌شوند.

-M وابستگی‌های make را تولید می‌کند. این گزینه قانونی مناسب برای make خروجی می‌دهد که وابستگی‌های فایل ورودی را توصیف می‌کند. پیش‌پردازنده به‌جای خروجی دادن نتیجهٔ پیش‌پردازش، یک قانون make شامل نام فایل شیء SPIR-V برای آن فایل منبع، یک دونقطه، و نام تمامی فایل‌های ضمیمه‌شده (included) را خروجی می‌دهد.

مگر اینکه به‌طور صریح (با -MT) مشخص شده باشد، نام فایل شیء SPIR-V در قوانین make تولیدشده از قواعد «نام‌گذاری فایل خروجی» مطابق با مرحلهٔ کامپایل -c پیروی می‌کند.

مشخص کردن -M متضمن فعال‌سازی -E است و هشدارها را با یک -w ضمنی فرونشانی می‌کند. به‌طور پیش‌فرض، خروجی در stdout نوشته خواهد شد، مگر اینکه -MF یا -o مشخص شده باشد.

نام فایل اطلاعات وابستگی را می‌توان با گزینه‌های -o و -MF تعیین کرد. هنگامی که هر دو مشخص شوند، گزینهٔ -o نادیده گرفته می‌شود.

مشخص کردن چندین فایل ورودی زمانی معتبر است که قوانین make در stdout نوشته شوند، یعنی نه -MF و نه -o مشخص نشده باشند. در صورت مشخص شدن -o یا -MF، تنها یک فایل ورودی مجاز است.

-MM یک نام مستعار برای -M است.

برای مثال، دستور glslc -M main.vert عبارت main.vert.spv: main.vert <other included files> را در stdout می‌ریزد. مثال‌های بیشتر در «مثال‌های تولید وابستگی» فهرست شده‌اند.

-MD به کامپایلر glslc دستور می‌دهد که هم منبع را کامپایل کند و هم وابستگی‌های make را تولید نماید. وابستگی‌ها در فایلی نوشته می‌شوند که نام آن به شرح زیر تعیین می‌شود: اگر گزینهٔ -MF مشخص شده باشد، از آرگومان آن استفاده می‌شود. در غیر این صورت، از نام فایلی که با افزودن .d به نام فایل حاوی نتایج کامپایل ایجاد شده، استفاده می‌شود.

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

برای مثال، glslc -c -MD main.vert فایل main.vert.spv را به‌عنوان فایل شیء SPIR-V و main.vert.spv.d را به‌عنوان فایل اطلاعات وابستگی تولید می‌کند. مثال‌های بیشتر در «مثال‌های تولید وابستگی» فهرست شده‌اند.

-MF این امکان را فراهم می‌کند که در هنگام استفاده با -M یا -MD، نام فایل اطلاعات وابستگی را مشخص کنید. استفاده از این گزینه همراه با چندین فایل ورودی نامعتبر است.

برای مثال، glslc -c -MD main.vert -MF dep_info فایل main.vert.spv را به‌عنوان فایل شیء SPIR-V و dep_info را به‌عنوان فایل اطلاعات وابستگی تولید خواهد کرد.

-MT این امکان را فراهم می‌کند که در هنگام استفاده با -M یا -MD، هدف (target) قانون صادرشده توسط تولید وابستگی را مشخص کنید. استفاده از این گزینه همراه با چندین فایل ورودی نامعتبر است.

برای مثال، glslc -M main.vert -MT target اطلاعات وابستگی زیر را در stdout می‌ریزد: target: main.vert <other dependent files>.

جدول ۳. مثال‌های تولید وابستگی

ورودی خط فرمان فایل خروجی کامپایل فایل خروجی وابستگی اطلاعات وابستگی
glslc -M main.vert <NA> <Stdout> main.vert.spv: main.vert
glslc -M a.vert b.vert <NA> <Stdout> a.vert.spv: a.vert
<NA> <Stdout> b.vert.spv: b.vert
glslc -M main.vert -o dep_info <NA> dep_info main.vert.spv: main.vert
glslc -M main.vert -MF dep_info <NA> dep_info main.vert.spv: main.vert
glslc -M main.vert -MT target <NA> <Stdout> target: main.vert
glslc -MD main.vert a.spv main.vert.spv.d main.vert.spv: main.vert
glslc -c -MD main.vert main.vert.spv main.vert.spv.d main.vert.spv: main.vert
glslc -c -MD a.vert b.vert a.vert.spv a.vert.spv.d a.vert.spv: a.vert
b.vert.spv b.vert.spv.d b.vert.spv: b.vert
glslc -S -MD main.vert main.vert.spvasm main.vert.spvasm.d main.vert.spvasm: main.vert
glslc -c -MD main.vert -MF dep_info main.vert.spv dep_info main.vert.spv: main.vert
glslc -c -MD main.vert -o obj obj obj.d obj: main.vert
glslc -c -MD main.vert -o obj -MF dep_info -MT target obj dep_info target: main.vert .TE "گزینه‌های مقیدسازی منابع (Resource Binding Options)" "-fauto-bind-uniforms" گزینهٔ -fauto-bind-uniforms به کامپایلر دستور می‌دهد در صورتی که یک binding صریح در منبع شیدر مشخص نشده باشد، به‌طور خودکار شماره‌های binding را به متغیرهای uniform اختصاص دهد. یک شمارهٔ binding صریح را می‌توان با استفاده از مشخص‌کنندهٔ چیدمان (layout qualifier) binding در منبع شیدر مشخص کرد. برای مثال: layout(binding = 12) uniform texture2D; "-fhlsl-iomap" گزینهٔ -fhlsl-iomap به کامپایلر دستور می‌دهد از تخصیص‌های ثبات (register) در HLSL به عنوان مقادیر binding استفاده کند. "-fimage-binding-base" گزینهٔ -fimage-binding-base [stage] base پایین‌ترین مقدار binding تخصیص‌یافتهٔ خودکار را برای تصاویر (images) تعیین می‌کند. در صورت مشخص شدن stage، فقط بر همان مرحله تأثیر می‌گذارد. برای HLSL، مقداری معادل یک واحد کمتر از base را تنظیم می‌کند. "-fsampler-binding-base" گزینهٔ -fsampler-binding-base [stage] base پایین‌ترین مقدار binding تخصیص‌یافتهٔ خودکار را برای نمونه‌بردارها (samplers) تعیین می‌کند. در صورت مشخص شدن stage، فقط بر همان مرحله تأثیر می‌گذارد. برای HLSL، مقداری معادل یک واحد کمتر از base را تنظیم می‌کند. "-ftexture-binding-base" گزینهٔ -ftexture-binding-base [stage] base پایین‌ترین مقدار binding تخصیص‌یافتهٔ خودکار را برای بافت‌ها (textures) تعیین می‌کند. در صورت مشخص شدن stage، فقط بر همان مرحله تأثیر می‌گذارد. برای HLSL، مقداری معادل یک واحد کمتر از base را تنظیم می‌کند. "-fubo-binding-base" گزینهٔ -fubo-binding-base [stage] base پایین‌ترین مقدار binding تخصیص‌یافتهٔ خودکار را برای شیء‌های بافر یکنواخت (Uniform Buffer Objects در GLSL) یا Cbufferها (در HLSL) تعیین می‌کند. در صورت مشخص شدن stage، فقط بر همان مرحله تأثیر می‌گذارد. برای HLSL، مقداری معادل یک واحد کمتر از base را تنظیم می‌کند. "-fcbuffer-binding-base" گزینهٔ -fcbuffer-binding-base [stage] base همانند -fubo-binding-base [stage] base است. "-fssbo-binding-base" گزینهٔ -fssbo-binding-base [stage] base پایین‌ترین مقدار binding تخصیص‌یافتهٔ خودکار را برای شیء‌های بافر ذخیره‌سازی شیدر (Shader Storage Buffer Objects در GLSL) تعیین می‌کند. در صورت مشخص شدن stage، فقط بر همان مرحله تأثیر می‌گذارد. این گزینه تنها بر کامپایل GLSL تأثیر می‌گذارد. "-fuav-binding-base" گزینهٔ -fuav-binding-base [stage] base مقداری معادل یک واحد کمتر از پایین‌ترین binding تخصیص‌یافتهٔ خودکار را برای نماهای دسترسی نامرتب (Unordered Access Views یا UAV) تنظیم می‌کند. در صورت مشخص شدن stage، فقط بر همان مرحله تأثیر می‌گذارد. این گزینه تنها بر کامپایل HLSL تأثیر می‌گذارد. "-fresource-set-binding" گزینهٔ -fresource-set-binding [stage] <reg0> <set0> <binding0> مجموعه‌توصیف‌گر (descriptor set) و binding را برای یک منبع HLSL بر اساس نام register تعیین می‌کند. برای مشخص کردن تنظیمات برای ثبات‌های بیشتر، سه‌گانه‌های متوالی متشکل از نام register، descriptor set و binding را اضافه کنید. مثال: # For a texture in register t1, use set 1 binding 0. # For a texture in register t2, use set 1 binding 3 glslc -x hlsl foo.frag -fresource-set-binding t1 1 0 t2 1 3 در صورت مشخص شدن stage، فقط بر همان مرحله تأثیر می‌گذارد. # Same as the previous example, but the settings only apply # to fragment (pixel) shaders. glslc -x hlsl foo.frag -fresource-set-binding frag t1 1 0 t2 1 3 "#line و __FILE__ مبتنی بر نام فایل مبدأ" این بخش توضیح می‌دهد که کامپایلر glslc چگونه نحو دستور #line و ماکروی __FILE__ را گسترش می‌دهد. به‌طور پیش‌فرض، کامپایلر glslc افزونهٔ GL_GOOGLE_cpp_style_line_directive را فعال می‌کند. این کامپایلر نحو گسترش‌یافتهٔ مذکور را در خروجی پیش‌پردازش‌شده (که با گزینهٔ -E به دست می‌آید) تولید خواهد کرد. 4 هشدار این بخش هنوز در حال تکامل است و احتمال تغییر آن وجود دارد. مشخصات GLSL مفهومی به نام رشته‌های مبدأ دارد. 3 مبدأ یک سایه‌زن (shader) منفرد، آرایه‌ای از رشته‌ها متشکل از نویسه‌های مجموعهٔ نویسه‌ها است. یک سایه‌زن منفرد از الحاق این رشته‌ها ایجاد می‌شود. 5 — بخش ۳.۲ از هر دو نسخهٔ 3.30 و 4.50 با توجه به مفهوم بالا، دومین پارامتر دستور #line باید یک عبارت ثابت از نوع عدد صحیح باشد که شمارهٔ رشتهٔ مبدأ را نشان می‌دهد. همچنین ماکروی __FILE__ «یک عدد صحیح ده‌دهی ثابت را جایگزین می‌کند که نشان می‌دهد کدام شماره از رشتهٔ مبدأ در حال حاضر در حال پردازش است.» کامپایلر glslc نحو استاندارد #line و __FILE__ را پیاده‌سازی می‌کند. همچنین افزونه‌ای با نام GL_GOOGLE_cpp_style_line_directive ارائه می‌دهد تا امکان استفاده از نام فایل‌های مبدأ به‌جای اندیس‌های عددی رشته‌های مبدأ فراهم شود. به طور مشخص، دستور #line پس از جایگزینی ماکرو می‌تواند یکی از سه شکل زیر را داشته باشد: #line line-number #line line-number integer-source-string-index #line line-number "source-filename" که در آن source-filename می‌تواند هر ترکیبی از نویسه‌ها به جز علامت نقل‌قول دوتایی (کوتیشن) باشد. (توجه داشته باشید که مطابق با مشخصات GLSL، «هیچ توالی گریز یا کاربرد دیگری برای بک‌اسلش به جز استفاده به عنوان نویسهٔ ادامهٔ خط وجود ندارد».) و اگر #line مبتنی بر نام فایل مبدأ استفاده شود، ماکروی __FILE__ به رشته‌ای بسط می‌یابد که محتوای آن نام فایلی است که درون علامت نقل‌قول دوتایی قرار گرفته است. نام فایل بر اساس آخرین مورد از موارد زیر تعیین می‌شود: 4 • نام فایل داده‌شده به کامپایلر glslc، 4 • آرگومان نام فایل در جدیدترین دستور #line (در صورت وجود). کامپایلر glslc با فعال‌سازی افزونه‌ی GL_GOOGLE_include_directive نحو include را به GLSL اضافه می‌کند. این کامپایلر دستورالعمل‌های #include را به درستی و با رفتارهای زیر پیش‌پردازش و جایگزین می‌کند. 4 هشدار این بخش همچنان در حال تکامل است. انتظار تغییرات را داشته باشید. اگر از دستورالعمل‌های #include در یک شیدر استفاده شود، خط #extension GL_GOOGLE_include_directive : enable در خروجی پیش‌پردازش‌شده تولید خواهد شد. افزونه‌ی GL_GOOGLE_cpp_style_line_directive به‌طور ضمنی توسط افزونه‌ی GL_GOOGLE_include_directive فعال می‌شود. آرگومان فایل برای #include باید درون علامت نقل‌قول دوتایی (double quotes) قرار گیرد. این مقدار باید یک مسیر نسبی باشد و از هر جداکننده‌ی مسیری که سیستم‌عامل پشتیبانی می‌کند استفاده کند. با این حال، آخرین عنصر مسیر — یعنی نام خود فایل — صرف‌نظر از نوع جداکننده‌ی مسیر استفاده‌شده، نباید شامل '/' یا '\' باشد. این مورد به عنوان خطا در نظر گرفته نمی‌شود، بلکه باعث رفتار تعریف‌نشده (undefined behavior) خواهد شد. به عنوان مثال، فرض کنید فایلی با نام f\ilename.vert روی یک سیستم‌عامل Unix وجود دارد. ایجاد یک دستورالعمل #include که بتواند این فایل را فراخوانی کند امکان‌پذیر نیست. علاوه بر این، گریزدهی (escape) هیچ نویسه‌ای در دستورالعمل #include امکان‌پذیر نیست، بنابراین آرگومان فایل نمی‌تواند شامل نویسه‌های خاصی باشد که در C نیاز به گریزدهی دارند. آرگومان فایل یک مسیر نسبی است که ابتدا با دایرکتوریِ خودِ فایلِ فراخواننده و سپس با تمام آرگومان‌های -I به ترتیب حضورشان در خط فرمان مطابقت داده می‌شود. اگر فایل پیدا نشود، glslc با ارسال خطا متوقف می‌شود.
2026-07-28