CMGEN(1)

🌸 NAME 🌸

okay so this is CMGEN(1) — section 1, user commands, the good stuff — and the whole page is about cmgen, aka filament material tools ✨. that's the vibe, that's the whole assignment, let's go 💅

🦋 DESCRIPTION 🦋

so cmgen is a command-line tool that generates SH and mipmap levels from an env map. that's the job, bestie, that's what she does 💖

Cubemaps and equirectangular formats are both supported, and the tool figures out which one you've got automatically — it peeks at the aspect ratio of the source image and just knows. no cap, no config, it reads the vibe check of your file's proportions 🌈

✨ Usages:

cmgen [options] <input-file>
cmgen [options] <uv[N]>

🎀 Supported input formats:

• PNG
• 8 and 16 bits Radiance (.hdr)
• Photoshop (.psd)
• 16 and 32 bits OpenEXR (.exr)

she's versatile, she's flexible, she contains multitudes 🫶

👑 OPTIONS 👑

💜 The standard ones

• --help, -h — prints this message. the "help me bestie" button 🥺
• --license — prints the copyright and license information. the receipts, the legal lore 📜
• --quiet, -q — Quiet mode. Suppress all non-error output. she goes silent, she stops yapping, only screams if something's actually wrong 💀
• --type=[cubemap|equirect|octahedron|ktx], -t [cubemap|equirect|octahedron|ktx] — specify the output type. the default is cubemap 🌸
• --format=[exr|hdr|psd|rgbm|rgb32f|png|dds|ktx], -f [exr|hdr|psd|rgbm|rgb32f|png|dds|ktx] — specify the output file format. heads up: ktx implies -type=ktx. and KTX files are always encoded with 3-channel RGB_10_11_11_REV data — that's not optional, that's just the rule 🎀
• --compression=COMPRESSION, -c COMPRESSION — format specific compression. and she is format specific fr fr:
  • KTX:
    • astc_[fast|thorough]_[ldr|hdr]_WxH, where WxH is a valid block size
    • s3tc_rgba_dxt5 etc
    • _FORMAT_METRIC_EFFORT
      • FORMAT is rgb8_alpha, srgb8_alpha, rgba8, or srgb8_alpha8
      • METRIC is rgba, rgbx, rec709, numeric, or normalxyz
      • EFFORT is an integer between 0 and 100
  • PNG: Ignored
  • PNG RGBM: Ignored
  • Radiance: Ignored
  • Photoshop: 16 (default), 32
  • OpenEXR: RAW, RLE, ZIPS, ZIP, PIZ (default)
  • DDS: 8, 16 (default), 32
• --size=power-of-two, -s power-of-two — Size of the output cubemaps (base level), 256 by default. Also applies to DFG LUT. little queen, pulling double duty 💅
• --deploy=dir, -x dir — Generate everything needed for deployment into <dir> 📦
• --extract=dir — Extract faces of the cubemap into <dir> 🧚
• --extract-blur=roughness — Blurs the cubemap before saving the faces using the roughness blur. soft focus, glamour shot ✨
• --clamp — Clamp environment before processing. boundaries, bestie 🫶
• --no-mirror — Skip mirroring of generated cubemaps (for assets with mirroring already backed in). if your asset already served the mirror look, don't double it 🌈
• --ibl-samples=numSamples — Number of samples to use for IBL integrations (default 1024) 🔥
• --ibl-ld=dir — Roughness pre-filter into <dir> 💜
• --sh-shader — Generate irradiance SH for shader code. for the shader girlies 👑

🔒 Private use only:

• --ibl-dfg=filename.[exr|hdr|psd|png|rgbm|rgb32f|dds|h|hpp|c|cpp|inc|txt] — Compute the IBL DFG LUT
• --ibl-dfg-multiscatter — If --ibl-dfg is set, computes the DFG for multi-scattering GGX
• --ibl-dfg-cloth — If --ibl-dfg is set, adds a 3rd channel to the DFG for cloth shading
• --ibl-is-mipmap=dir — Generate mipmap for pre-filtered importance sampling
• --ibl-irradiance=dir — Diffuse irradiance into <dir>
• --ibl-no-prefilter — Use importance sampling instead of prefiltered importance sampling
• --ibl-min-lod-size — Minimum LOD size [default: 16]
• --sh=bands — SH decomposition of input cubemap
• --sh-output=filename.[exr|hdr|psd|rgbm|rgb32f|png|dds|txt] — SH output format. The filename extension determines the output format
• --sh-irradiance, -i — Irradiance SH coefficients
• --sh-window=cutoff|no|auto (default), -w cutoff|no|auto (default) — SH windowing to reduce ringing
• --debug, -d — Generate extra data for debugging

💀 bestie reminder: the stuff under Private use only is literally labeled private use only. it's giving "you can look but this isn't for you." proceed with the appropriate amount of caution 🫶

💖 and that's the page 💖

and oh — quick note that the section at the bottom of this thing is dated October 2021, and the source/version line reads cmgen is a command-line tool f... (yes, it's literally cut off like that in the original, iconic behaviour honestly), all stamped with CMGEN(1). that's a wrap, mwah, go generate some env maps 💅✨