For instructions on how to run glsl-reduce as a stand-alone tool, see the glsl-reduce manual for stand-alone reducing.
glsl-reduce SHADER_JOB --reduction-kind KIND [--preserve-semantics] [--error-string ERROR] [other options]See below for common examples.
glsl-reduce takes a shader job SHADER_JOB (a .json file) as an argument
as well as further arguments or options to specify the interestingness test.
glsl-reduce will try to simplify the given shader job to a smaller,
simpler shader job that is still deemed "interesting".
SHADER_JOB should be a .json shader job file that represents all shaders and metadata needed to
render an image. If the shader job is named foo.json,
glsl-reduce will look for corresponding shaders alongside this file named
foo.frag, foo.vert and foo.comp,
of which there must be at least one,
and will apply reduction to all such shaders that are present.
On termination, the reduced shader job will be
named foo_reduced_final.json (with associated shader files).
KIND specifies the "kind of reduction" (i.e. the type of interestingness test),
the most common being:
- ABOVE_THRESHOLD: a shader job is interesting if it produces an
image that is sufficiently different from a reference image.
This reduction kind is normally used with
--preserve-semantics, otherwise the reducer will change the semantics of the shaders and the reference image will no longer be valid. - NO_IMAGE:
a shader job is interesting if it does not produce an
image and, optionally, the run log from running the shader job includes the
regular expression
ERROR. This reduction kind is typically used without--preserve-semantics, so the reducer can change the semantics of the shader; we are usually reducing a crash or incorrect shader compilation error, so changing the semantics of the shaders is fine, as they should still compile and run. Note that the reducer always produces valid shaders that should compile.
Given a shader job shader-job.json,
the following are common reduction commands:
# Wrong image reduction.
glsl-reduce shader-job.json --preserve-semantics --reduction-kind ABOVE_THRESHOLD --reference reference.info.json
# No image reduction:
glsl-reduce shader-job.json --reduction-kind NO_IMAGE --error-string "Fatal signal 11"
# Custom interestingness test:
glsl-reduce shader-job.json interestingness_test.shNote regarding reference.info.json above: the reducer will look for reference.png alongside this file
and use it as the reference image.
For the custom interestingness test, see the glsl-reduce manual for stand-alone reducing. Note that the custom interestingness test can still be used on shader jobs produced by glsl-generate.
Options:
Reduce GLSL shaders, driven by a criterion of interest.
positional arguments:
shader_job Path of shader job to be reduced. E.g.
/path/to/shaderjob.json
interestingness_test Path to an executable shell script that should
decide whether a shader job is interesting. Only
allowed (and then also required) when performing
a custom reduction, which is the default.
optional arguments:
-h, --help show this help message and exit
--reduction-kind REDUCTION_KIND
Kind of reduction to be performed. Options are:
CUSTOM Reduces based on a user-
supplied interestingness test.
NO_IMAGE Reduces while image
generation fails to produce an image.
NOT_IDENTICAL Reduces while produced
image is not identical to reference.
IDENTICAL Reduces while produced
image is identical to reference.
BELOW_THRESHOLD Reduces while histogram
difference between produced image and reference
is below a threshold.
ABOVE_THRESHOLD Reduces while histogram
difference between produced image and reference
is above a threshold.
VALIDATOR_ERROR Reduces while validator
gives a particular error
ALWAYS_REDUCE Always reduces (useful for
testing)
(default: CUSTOM)
--metric METRIC Metric to be used for image comparison. Options
are:
HISTOGRAM_CHISQR
PSNR
(default: HISTOGRAM_CHISQR)
--reference REFERENCE Path to reference .info.json result (with image
result) for comparison.
--threshold THRESHOLD Threshold used for histogram differencing.
(default: 100.0)
--timeout TIMEOUT Time in seconds after which execution of an
individual variant is terminated during
reduction. (default: 30)
--max-steps MAX_STEPS The maximum number of reduction steps to take
before giving up and outputting the final reduced
file. (default: 250)
--retry-limit RETRY_LIMIT
When getting an image via the server, the number
of times the server should allow the client to
retry a shader before assuming the shader crashes
the client and marking it as SKIPPED. (default: 2)
--verbose Emit detailed information related to the
reduction process. (default: false)
--skip-render Don't render the shader on remote clients. Useful
when reducing compile or link errors. (default:
false)
--seed SEED Seed to initialize random number generator with.
(default: 1354327545)
--error-string ERROR_STRING
String checked for containment in validation or
compilation tool error message.
--server SERVER Server URL to which image jobs are sent.
--token TOKEN Client token to which image jobs are sent. Used
with --server.
--output OUTPUT Output directory. (default: .)
--preserve-semantics Only perform semantics-preserving reductions.
(default: false)
--stop-on-error Quit if something goes wrong during reduction;
useful for testing. (default: false)
--swiftshader Use swiftshader for rendering. (default: false)
--continue-previous-reduction
Carry on from where a previous reduction attempt
left off. (default: false)