Environment Variables

Environment variables

Programs made by BlitzLLVM and the tools read a few environment variables. All of them start with BLITZLLVM_, so they do not collide with anything else, and the part after it says what kind of variable it is:

Name	Kind
BLITZLLVM_LEGACY_<BEHAVIOUR>	Goes back to what the original Blitz3D or BlitzPlus did, where BlitzLLVM does something else by default. Off by default.
BLITZLLVM_DEBUG_<NAME>	Turns on checks or reports for finding errors or comparing. Off by default.
BLITZLLVM_TEST_<NAME>	Hooks for the tests of BlitzLLVM itself. Not meant for programs.
BLITZLLVM_<AREA>_<NAME>	Everything else, grouped by the area it affects (SPATIAL_GRID, ASYNC, FULLSCREEN, PROFILE, ...).

A switch is 1 or 0 (true/false, yes/no and on/off work as well, in any case). Any other value than those that mean no counts as yes, and a variable that is set but empty counts as not set. A switch that is on by default is turned off with 0 and has no NO_ in its name: BLITZLLVM_SPRITE_HULL=0. A switch that is off by default is turned on with 1. The runtime reads all of them through one function, so they all work like this.

Variables of the compiler (blitzcc) and the tools are read when they start. The runtime reads the BLITZLLVM_ variables (and the old BLITZ_ names) once, when the program starts, before any of its code runs. A program that changes one with SetEnv changes only what GetEnv$ and the programs it starts see; it does not change how the runtime behaves, so a program can't switch features that are meant for the person who starts it. Set the variable before starting the program.

Behaviour of the original

Variable	Default	What it does
BLITZLLVM_LEGACY_AUDIO_RESAMPLING	0	Resamples sounds with linear interpolation, like FMOD in the original, see Sound-Resampling.

Settings

Variable	Default	What it does
BLITZLLVM_CPU	native	Lowers the CPU features the runtime may use: baseline, v2, v3, v4 (x86-64 levels), native or -<feature>, separated by commas, see CPU-Features.
BLITZLLVM_ASYNC_LOAD	0	Loads pictures and models on other threads, see Asynchronous-Loading.
BLITZLLVM_ASYNC_SAVE	0	Saves pictures on other threads, see Saving-Pictures.
BLITZLLVM_GPU_DRAWS	0	Draws the meshes that stay as they are from a table that the GPU drives (experimental), see GPU-Driven-Draws.
BLITZLLVM_FULLSCREEN_FILTER	by size	nearest or linear for the picture of a fullscreen program, see Fullscreen.
BLITZLLVM_GUI_SCALE	the scale of the display	How many pixels a unit of the windows of BlitzPlus is, see CreateWindow: 0 (or 1) makes every unit one pixel, as the original has it; 1.5 or 2 scales the windows as a display of that scale would, see DPI-Scaling.
BLITZLLVM_FULLSCREEN_SCALE	smooth	integer only enlarges the picture by whole numbers, see Fullscreen.
BLITZLLVM_VOLUME_FALLOFF	new	The curve that the volume of 3D sounds falls off by: new, legacy (the curve of the original) or soloud (the curve of SoLoud), see CreateListener.
BLITZLLVM_ENTITY_LIGHTING	0	The EntityLighting mode of entities that were not given one: 1 lights every pixel instead of every vertex.
BLITZLLVM_NET_IPV6	1	0 makes the network commands use IPv4 only, see IPv6.
BLITZLLVM_NETGAME_PORT	40500	The TCP port of multiplayer games, see Multiplayer.
BLITZLLVM_HEADLESS	0	Runs without a window and without sound; dialogs answer with what is safe. For automated runs.
BLITZLLVM_DIALOG_ANSWER	not set	The number of the button that a dialog presses without being shown, for automated runs, see Multiplayer.
BLITZLLVM_OIT	0	Adds up blended things without looking at their order, like GraphicsOrderIndependentTransparency 1; 2 is the moment based kind, 3 the sorted samples of a pixel with a weighted tail (4 samples), 4 the same with 8, 5 the exact reference by depth peeling (slow, for reference pictures).
BLITZLLVM_OIT_LAYERS	128	Most layers of BLITZLLVM_OIT=5: one pass over the see-through things for each.
BLITZLLVM_ALLOC_SYSTEM	0	Uses the allocator of the system instead of the one of the runtime, see Memory.

Features that can be turned off

These are on, 0 turns them off, which is useful to compare speed or pictures.

Variable	What it controls
BLITZLLVM_SPRITE_HULL	The outline that fits the picture of a sprite, see Sprite-Shapes.
BLITZLLVM_BLEND_DITHER	Dither 2 through reading the target in the shader (HWDither).
BLITZLLVM_DITHER_TEMPORAL	The noise of Dither moving from picture to picture (DitherTemporal).
BLITZLLVM_TRANSPARENCY_DISTANCE_SORT_MODE	1 orders see-through draws by View Distance and not by distance in space (TransparencyDistanceSortMode), 0 by default.
BLITZLLVM_DITHER_LOCAL_READ	Blending in the shader through the local read extensions (only used where the GPU has them).
BLITZLLVM_DITHER_INTERLOCK	Blending in the shader through the pixel interlock (only used where the GPU has it and the local read extensions are missing or off).
BLITZLLVM_COLLISION_BROADPHASE	The broad phase of the collisions.
BLITZLLVM_PICK_BROADPHASE	The broad phase of the picks (LinePick, EntityPick, CameraPick, EntityVisible), which only looks at the entities near the line.
BLITZLLVM_PICK_STATS	A file name. Every 1000 picks the counters of the pick broad phase (picks that used it, trees made, entities found per pick) are written there, to find out why it helps or not on a machine.
BLITZLLVM_LIGHT_GRID	The grid that finds the lights that reach a mesh.
BLITZLLVM_LIGHT_CACHE	Remembering which lights reach a mesh.
BLITZLLVM_SPATIAL_GRID	The grid that finds the meshes that are in view, see Spatial-Grid.
BLITZLLVM_MESH_WRITE_ONLY	The memory of the vertex and index buffers of meshes: video memory the CPU can reach, where there is some, instead of memory in RAM that the GPU reads over PCIe.
BLITZLLVM_VRAM_LIMIT_MB	Pretends that the program has only this much video memory (0 or unset: all there is). For testing what the program does when video memory is full: textures without flag 256 go to system memory, the others stop the program with an "out of video memory" error, and AvailVidMem reports less.
BLITZLLVM_DEFRAG_TEST	Moves the allocations of textures and images together before every texture is made, instead of only when video memory has no gap that is big enough. For testing; it costs time.
BLITZLLVM_DEFRAG_REPORT	Prints how many images a defragmentation moved.
BLITZLLVM_ALLOC_RELEASE	Giving the memory of allocator spans that stayed empty for a second back to the system, see Memory.
BLITZLLVM_DEVICE_RECOVERY	Making the graphics again after the graphics device was lost, see Lost-Graphics-Device. Off, a lost device ends the program and no copies of the pixels are kept.

Tuning

Variable	Default	What it does
BLITZLLVM_SPATIAL_GRID_SCAN_SHARE	built in	The share of the meshes in the cells that are in view above which the grid is not used for that look, see Spatial-Grid.
BLITZLLVM_SPATIAL_GRID_MAX_MOVED	built in	How many meshes may move in a frame before the grid is left alone.
BLITZLLVM_COLLISION_BACKEND	jolt	What tells which triangles of a mesh are near the path of a mover in UpdateWorld: jolt asks the blitzphysics library for meshes of at least 64 triangles, legacy looks at all of them. The triangles are tested the same either way, so the collisions are too. Skinned meshes and terrains always look at all of them.
BLITZLLVM_PICK_BACKEND	jolt	What finds the hits of LinePick, EntityPick, CameraPick and EntityVisible: jolt hands meshes of at least 32 triangles to the blitzphysics library, which is much faster on large meshes. Skinned meshes, terrains and small meshes always use the built in test, as does every mesh with legacy.
BLITZLLVM_THREADS	half of the cores, at most 8	How many threads share work that is the same for every element, such as making the clusters that the GPU culls meshes with. The thread that renders counts as one, 1 does the work on that thread alone.
BLITZLLVM_PIN_CORE0	1 on Windows, ignored elsewhere	The thread that runs the program prefers the first CPU the process may use (usually the one that boosts highest), and the helper threads (work pool, loaders, submission and window threads) prefer the other CPUs and not the SMT sibling of that one. This is only a hint to the scheduler (ideal processor). Other systems do nothing. 0 turns it off.
BLITZLLVM_DEVICE_LOSS_COOLDOWN_MS	300000	How many milliseconds without a lost graphics device make the next loss count as the first again; the third loss within it ends the program, see Lost-Graphics-Device.

Debugging and profiling

Variable	Default	What it does
BLITZLLVM_PROFILE_FPS	0	Prints the frames per second and the timers of the runtime once a second. Needs a program made with --profile or -d. Changed while the program runs with ProfileFPS (and ProfileEnable for the timers).
BLITZLLVM_PROFILE_SLOW	0	A number of milliseconds: every frame that takes longer than that is listed on stderr, with the frame number and the timers of just that frame (collect, draws, clusters, record, waiting for the GPU, ...) and the GPU pass times that came back for it and the three frames after it, so a single stutter shows in a long run. Needs a program made with --profile or -d. Changed while the program runs with ProfileSlow.
BLITZLLVM_PROFILE_OUTPUT	not set	A file that receives the text of the profiling (BLITZLLVM_PROFILE_FPS and BLITZLLVM_PROFILE_SLOW) instead of the standard error output. Needs a program made with --profile or -d. ProfileOutput changes it while the program runs and ProfileValue gives the numbers of the last frame to the program.
BLITZLLVM_PROFILE_SAMPLE	not set	The file that receives where the program spends its time (sampled every millisecond). Windows only, needs --profile. With -g or -d as well, <file>.stacks also receives the call stacks, see below. ProfileSample starts and stops it while the program runs.
BLITZLLVM_DEBUG_ALLOC	0	Fills freed and new blocks with patterns and stops when a freed block is written to or freed twice, see Memory.
BLITZLLVM_DEBUG_ALLOC_STATS	0	Counts the blocks and bytes that were not freed and reports them at the end, see Memory.
BLITZLLVM_DEBUG_ALLOC_RELEASE	0	Prints a line to stderr for every sweep that gave empty allocator spans back to the system: how many, when, and how long the longest was empty, see Memory.
BLITZLLVM_MESH_REPORT	0	Prints the memory flags of the first four vertex and index buffers of meshes (device local, host cached).
BLITZLLVM_DEBUG_SYNC_GPU	0	Waits for the GPU after every frame, as if it had no thread.
BLITZLLVM_DEBUG_CHECK_LIGHTS	0	Rates the lights of all meshes as well and stops if the grid and the cache gave different ones.
BLITZLLVM_DEBUG_SPATIAL_GRID	0	Prints how many meshes the grid found each frame.
BLITZLLVM_SIMULATE_DEVICE_LOSS	not set	Flip numbers (3,8) at which the graphics device counts as lost, by making all the graphics again on a device that works, see Lost-Graphics-Device.
BLITZLLVM_SIMULATE_DEVICE_LOSS_LATE	0	The simulated loss is only noticed after the Flip, so the calls up to the next Flip run against a lost device.

Format of the call stack file

x64 Windows programs built with --profile and -g (or -d) write <file>.stacks next to <file>, which keeps its format (the load address of the program, then one instruction address per sample). The call stacks are not recorded without the symbols, as they could not be turned into names. All numbers are little endian. The file starts with a header, followed by one record per sample, in the order of <file>; it grows every four seconds.

Header	Size	What
magic	4	BBST
version	4	1
max_frames	4	How many addresses a record has room for (8)
base	8	Where the program is loaded

Record	Size	What
frame	4	How many Flip calls there were before the sample, to cut the samples per phase
depth	4	How many of the addresses are used
microseconds	8	Since the sampler started
addresses	8 * max_frames	Where the sample was, then the return addresses of the callers (subtract base and look up in the debug information)

Compiler and tools

Variable	What it does
BLITZLLVM_CC	The C compiler blitzcc hands the program to.
BLITZLLVM_HARDENING=0	Leaves out the hardening flags that blitzcc gives the C compiler for Linux and macOS programs (stack protector, _FORTIFY_SOURCE, read-only relocations, control flow protection).
BLITZLLVM_USERLIBS	The directory with the user libraries and their .decls files, see Blitz-Tidy.

Tests

BLITZLLVM_TEST_PRESENT, BLITZLLVM_TEST_EVENTS, BLITZLLVM_TEST_LAYOUT, BLITZLLVM_TEST_WINDOW_FLAGS, BLITZLLVM_TEST_EXTRA_SURFACES, BLITZLLVM_TEST_LAZY_DEVICE, BLITZLLVM_TEST_PRESENTERS and BLITZLLVM_TEST_WINDOW_SHOTS are read by the runtime and let the tests of BlitzLLVM look at what a window shows, press keys, open and close more windows than Graphics has, make the graphics device before the window of Graphics, show pictures in windows with a thread each, and save what every window of the BlitzPlus GUI shows as a picture; the test programs and their scripts read a few more (BLITZLLVM_TEST_PROGRAM, BLITZLLVM_TEST_DEBUG, ...). They can change at any time and are not for programs. The tests of BlitzLLVM set BLITZLLVM_TEST_LIVE_ENV=1 before starting a program so that the program can set these with SetEnv; that variable is read at the start as well and is not for programs.

Old names

Before these names were unified the variables started with BLITZ_. The old names still work while the new one is not set, and a program made with -d prints a note once for every old name it used. They will be removed; BLITZ_NO_<FEATURE>=1 is BLITZLLVM_<FEATURE>=0 now.

Old name	New name
BLITZ_HEADLESS, BLITZ_DIALOG_ANSWER, BLITZ_NETGAME_PORT	BLITZLLVM_HEADLESS, BLITZLLVM_DIALOG_ANSWER, BLITZLLVM_NETGAME_PORT
BLITZ_ASYNC_LOAD, BLITZ_ASYNC_SAVE, BLITZ_FULLSCREEN_FILTER, BLITZ_FULLSCREEN_SCALE	the same after BLITZLLVM_
BLITZ_AUDIO_CLASSIC	BLITZLLVM_LEGACY_AUDIO_RESAMPLING
BLITZ_NO_SPRITE_HULL, BLITZ_NO_BLEND_DITHER, BLITZ_NO_LOCAL_READ_DITHER, BLITZ_NO_INTERLOCK_DITHER, BLITZ_NO_BROADPHASE, BLITZ_NO_LIGHT_GRID, BLITZ_NO_LIGHT_CACHE, BLITZ_NO_SPATIAL_GRID	BLITZLLVM_SPRITE_HULL=0, BLITZLLVM_BLEND_DITHER=0, BLITZLLVM_DITHER_LOCAL_READ=0, BLITZLLVM_DITHER_INTERLOCK=0, BLITZLLVM_COLLISION_BROADPHASE=0, BLITZLLVM_LIGHT_GRID=0, BLITZLLVM_LIGHT_CACHE=0, BLITZLLVM_SPATIAL_GRID=0
BLITZ_GRID_SCAN_SHARE, BLITZ_GRID_MAX_MOVED	BLITZLLVM_SPATIAL_GRID_SCAN_SHARE, BLITZLLVM_SPATIAL_GRID_MAX_MOVED
BLITZ_GRID_DEBUG, BLITZ_SYNC_GPU, BLITZ_CHECK_LIGHTS, BLITZ_ALLOC_DEBUG, BLITZ_ALLOC_STATS	BLITZLLVM_DEBUG_SPATIAL_GRID, BLITZLLVM_DEBUG_SYNC_GPU, BLITZLLVM_DEBUG_CHECK_LIGHTS, BLITZLLVM_DEBUG_ALLOC, BLITZLLVM_DEBUG_ALLOC_STATS
BLITZ_ALLOC_SYSTEM	BLITZLLVM_ALLOC_SYSTEM
BLITZ_FPS, BLITZ_SAMPLE	BLITZLLVM_PROFILE_FPS, BLITZLLVM_PROFILE_SAMPLE
BLITZ_TEST_PRESENT, BLITZ_TEST_EVENTS, BLITZ_TEST_LAYOUT, BLITZ_TEST_WINDOW_FLAGS	the same after BLITZLLVM_

One difference to the old behaviour: BLITZ_HEADLESS and BLITZ_AUDIO_CLASSIC counted as on with any value, also 0. Now 0 is off.