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; variables of the runtime are read by the program when it starts, or at the first use of the thing they control.

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_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_FULLSCREEN_FILTER	by size	nearest or linear for the picture of a fullscreen program, see Fullscreen.
BLITZLLVM_FULLSCREEN_SCALE	smooth	integer only enlarges the picture by whole numbers, see Fullscreen.
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_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_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_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.

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.

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.
BLITZLLVM_PROFILE_SAMPLE	not set	The file that receives where the program spends its time (sampled every millisecond). Windows only, needs --profile.
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_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.

Compiler and tools

Variable	What it does
BLITZLLVM_CC	The C compiler blitzcc hands the program to.
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 and BLITZLLVM_TEST_WINDOW_FLAGS are read by the runtime and let the tests of BlitzLLVM look at what a window shows and press keys; 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.

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.