trim: Move explanatory message from stdout to stderr.

This prevents this message from corrupting the output of:

apitrace trim --print-callset ... > callset-file

trim: Print a warning message when doing dependency analysis.

As requested by José prior to merging this code upstream.

trim: Move TraceAnalyzer out of cli_trim.cpp into its own file.

This class had long since outgrown where it was living at the top of
cli_trim.cpp. Thanks to José for recommending this.

trim: Never trim any glBindTexture calls.

This shouldn't be necessary. I've got a case where trimming out the
glBindTexture of an unused texture changes the behavoir, which
shouldn't be the case.

While I'll still try to track down that bug, this patch provides
conservative behavior that hopefully won't break anything. (The only
real downside is the potential of an implementation getting confused
by a glBindTexture with a value that was not returned by
glGenTextures).

trim: Never trim any textures bound within a display list.

This is conservative. The more efficient approach would create a
resource link from the display list to the texture, but that will wait
for when we actually have display-list resources.

trim: Add support for display lists.

The calls specified between glNewList and glEndList need to have
special treatment. For now we do the simplest thing and
unconditionally include all such calls in the trim output.

Eventually we will want to track display-list resources similar to
textures and trim away unused display lists.

trim: Conservatively make shader programs depend on textures

Some shader programs sample textures, so if the shader is included in
the trimmed output the texture needs to be included as well.

We don't have support inside of "apitrace trim" to parse GLSL to find
names of samplers to find these dependencies. Instead, we provide here
a simple heuristic:

In order to sample a texture, the OpenGL program must associate the
name of a texture unit with a location in the shader by calling
glUniform1i (or glUniform1iv). So we can notice whenever texture-unit
names are being passed and create a dependency from the shader to all
texture targets for that unit.

This is conservative on two fronts:

  1. The value being passed to glUniformi might only be coincidentally
     the same as a texture-unit name and be actually unrelated to
     texture sampling.

  2. The shader likely doesn't depend on all texture targets, but
     again we can't know which without looking inside the shader, so
     we associate all of them.

trim: Perform correct state tracking for glActiveTexture

Not all glBindTexture calls are created equal. With calls to
glActiveTexture intervening, calls to glBindTexture are actually
operating on indenpendent texture units.

It's actually quite easy to simple insert the number of the currently
active texture unit into the name of the texture target resource.

trim: Add a new --print-callset option.

This is useful whenever one has a need to manually tweak the trim operation.

Simply run:

apitrace trim --print-callset --frames=<whatever> --calls=<whatever>

as desired. Then take the resulting callset that is printed and run:

apitrace trim --calls=<callset> --exact

This should yield an identical trimming operation. Then this operation
can be tweaked by appending call ranges to the --calls option,
deleting rangess from the --calls option, or by appending a new
--frames option.

trim: Add a --frames option for selecting frames to trim.

This accepts a "frame set" which has syntax identical to the "call
set" of the existing --calls option. So, one could trim to just the
drawing operations of the first 10 frames of a trace with
--frames=0-9/draw.

trim: Abstract common stringstream idioms into shared functions.

Using the new providef, linkf, and unlinkf functions shrinks the code
a bit. It's tempting to provide <stdargs> functions with full
printf-like formatting, but it's really not necessary as of yet.

trim: Fix bug linking incorrect programs to shaders through samplers.

Previously, the code was mapping locations returned by
glGetUniformLocation and looking in the location map to try ot
determine which program to link in a glUniform1i call. This was
entirely bogus, as distinct programs do not have distinct location
spaces.

The correct answer is to simply track the currently active program and
link it to textures being bound to shaders.

trim: Add support for trimming out unused shaders.

The provide/consume analysis framework is finally starting to show
dividends. This is a fairly significant amount of new functionality
for "apitrace trim" yet it requires relatively little new code.

trim: Drop unused textures while trimming.

We introduce a new dependencies map so that some resources can depend
on other resources, effectively providing a tree of calls that need to
be included when the user requests a particular call be preserved in
the trim.

For example, a SwapBuffers call depends on the "framebuffer".
A rendering operation makes "framebuffer" depend on "render-state".
Enabling texturing makes "render-state" depend on "texture-target-FOO".
Binding a texture makes "texture-target-FOO" depend on "texture-X".
Uploading a texture makes the current call provide "texture-X".
Creating a texture makes the current call provide "texture-X".

This way, if a particular SwapBuffers call is included in the trimmed
output, all of the above will be included. Otherwise, if a SwapBuffers
is trimmed, then the "framebuffer" dependencies will be cleared and
none of the above calls will be included in the trimmed output.

trim: Close some memory leaks.

The parse_call() function allocates an object and returns a pointer,
so we need to explicitly call delete on that object.

trim: Trim most drawing operations outside of the user-specified range

Care is taken to consider a glBegin/glEnd block as a single drawing
operation, (so that it will enitrely included or entirely trimmed).

We're also careful to avoid trimming any drawing operation when there
are active side effects (other than rendering to the default
framebuffer). For example, if there is an active binding of
GL_FRAMEBUFFER or GL_DRAW_FRAMEBUFFER to any buffer object, or if we
are withing a glBeginTransformFeedback/glEndTransformFeedback block;
in any of these cases the drawing operation will not be trimmed.

trim: Avoid doing any analysis past the end of the user-specified range.

This doesn't actually change any results, (the dependency analysis
already ensures that calls beyond the range won't get included).

But this is a nice optimization to prevent wasted time and memory
analyzing these calls that are really easy to reject.

trim: Add a more condensed usage message for error cases.

When explicitly asking for help, ("apitrace help trim" or "apitrace
trim --help"), the complete help message is still provided.

But when an error case triggers a usage message, (such as an invalid
command-line argument), a more compact usage message is provided so as
to not overwhelm the error message (such as "invalid argument:
--foo").

trim: Prune uninteresting calls while trimming (unless --no-prune is passed)

Examine the CALL_FLAG_UNINTERESTING flag and leave out these calls
when trimming. These calls are generally the calls that have no side
effects, (such as query functions). Some calls without side effects
might be considered interesting, (such as glGetError returning a
non-zero error).

This pruning behavior can be avoided by passing the new --no-prune
option (or the new --exact option which is identical to passing both
--no-prune and -no-deps).

trim: Complain if given extraneous arguments.

Previously additional arguments were silently ignored, (which can lead
to confusion if the user expects to be able to specify a bare callset
on the command line rather than specifying a --calls option).

trim: Add framework for performing dependency analysis while trimming

The current analysis is as brain-dead as possible. All calls are
interpreted as affecting the current "state" resource, and all calls
are also interpreted as depending on the current "state". In other
words, no calls at all will be trimmed. Obviously, this is not useful
analysis, but all the framewok is now present for easily doing more
interesting things.

A new --no-deps option is now made available to "apitrace trim" so
that users can avoid all dependency analysis and still get the prior
behavior where only calls explicitly included in the --calls option
are included in the trim output.

docs: Eliminate most references to glretrace.

cli_retrace: Forward all options to retrace program.

cli: Auto-detect retrace for dump-images too.

cli: Guess the retrace excutable adequate for the trace.

d3d10,d3d11: Take the UpdateSubresource box in full consideration.

Merge branch 'union-type'

dump: Pretty print anonymous structure members.

d3d10/d3d11: Complete union support.

d3d10: Add missing flags.

dxgi: Support tracng DWM process.

d3dretrace: Dump d3d10 snapshots too.

d3d10/d3d10_1: Expose DXGI entrypoints.

specs: Initial attempt to support unions.

d3d10/d3d11: Use consistent members for buffer views.

cli: Rename replay -> retrace.

For consistency with the current terminology.

cli: Rename replay -> retrace.

For consistency with the current terminology.

cli: Add a simple "apitrace replay" sub-command.

This calls out to glretrace in order to replay a trace. Currently it
only supports the -w,--wait option, (and not yet any of the profiling
support).

With this command and the existing "apitrace dump-images", we're quite
close to being able to relegate glretrace to an implementation detail
used by the apitrace program, (such that soon, it won't be necessary
to provide glretrace on the user's PATH).

dump-images: Execute glretrace from source dir when running uninstalled

Previously, we've had code to carefully find wrappers and scripts
relative to an apitrace binary being run from an uninstalled
directory. This is extremely useful while testing an experimental
feature before installing said experimental code.

Similarly, provide a findProgram function to do the same thing for an
executable program and use it within "apitrace dump-images" when
invoking glretrace.

Move trace::findWrapper to trace_resource.cpp

It's not actually used outside of trace_tools_trace.cpp, but it is so
similar to the existing trace::findScript in trace_resource.cpp that
there are benefits to having them defined in the same file.

d3d: And d3dcommonsize.hpp too.

sigh..

d3d8: Add missing d3d8size.hpp file.

d3d8: Update specs to match d3d9.

And vice versa.

pickle: Try to silence clang warnings.

gltrace: Rely on polymorphism for indices instead of special case.

gltrace: Respect length argument in glShaderSource(ARB)

tracediff: Merge tracediff2.py and tracediff.py

doc: Update examples to use call 0.

Call numbers start from 0, but examples gave the impression it started
from call 1.

d3d11: Ensure IDXGIFactory1 interface is not forgotten.

specs: Mark CheckMultisampleQualityLevels as no side effects / verbose.

d3d11: Several spec fixes.

retrace: Use different methods for writing int/floats.

More efficient code, less compiler warnings.

gui: Silence unused var warning.

os: Fix thread copy constructor.

retrace: Fix MSVC build.

d3dretrace: More robust against DXGI missing calls.

parse: More flags.

d3dretrace: Basic D3D11 snap-shooting.

parse: recognize more rendering calls.

retrace: Allow multiple dumpers to co-exist.

d3d11: Fix map swizlling.

Merge branch 'modules'

Update use/mention of options.

glretrace: Use getopt rather than manual parsing of command-line options

This allows for better consistency with other apitrace command-line
interface. It also provids for several new full-name options where
previously only a single-letter option was available,
(--snapshot-prefix for -s, --verbose for -v, et.).

We use getopt_long_only here to maintain compatibility with the older
style of long options with one dash (-core) as well as providing the
double-dash version )--core).

It would now be quite convenient to regularize the command-line
interface to glretrace in several ways. None of these are performed in
this commit to avoid breaking compatibility with existing scripts,
etc.:

  * Give multi-letter, abbreviated options (--pcpu, etc.) proper
    long-form names (--profile-cpu).

  * Combine related options under a single name (--pcpu and --pgpu
    could be something like --profile=cpu,gpu).

  * Combine options with the same meaning that would never be used
    independently. Snapshot generation and snapshot comparison are
    different modes. Meanwhile, prefix selection and call selection
    should apply identically to either mode. So both modes can use a
    single set of options (--prefix and --calls) rather than having
    separate --snapshot-prefix and --snapshot options.

Move static boolOption function to trace::boolOption

Other programs will also want to be able to parse Boolean command-line
options, so we should share this code in order to easily get
consistent behavior.

wrappers: Cleanup .def files formating.

d3d11: Export DXGI entrypoints.

Some apps use them.

d2d: Silence MinGW linker warnings.

retrace: More diagnostic information.

d3dretrace: Handle Software devices.

d2d: Make it actually work.

trace: Fix thinko on error checking.

d3dretrace: Merge d3d9 and d3d10 retracing.

d2d1,dwrite: Trace both APIs together.

d3dretrace: Drop retraceModule helper

d3dretrace: Single retrace for d3d10 and higher

d3dretrace: Eliminate dependencies from d3d9state.

d3dretrace: Allow multiple dispatches in the same file.

os: DLL abstraction.

gl: Handle ClearBufferData blobs.

d3dretrace: Eliminate differences between d3d9/d3d10.

ddraw: Remove custom tracer.

d2d: Eliminate custom tracers.

specs: Allow an API to spread across multiple modules.

d3d1x: Cleanup specs.

specs: Use StdMethod accurately.

Merge branch 'd2d'

gltrace: Don't use struct for Context.

snappy: Always build with NDEBUG define.

gui: Make FrameDataProvider destructor virtual.

d3dretrace: Fix MSVC build.

d3d11: Trace UpdateSubresource blobs.

retrace: More useful warnings for object mismatches.

d3d10,d3d11: Rudimentary retrace support.

Doesn't work often, in practice because dxgi calls are missing from traces.

d3d10/d3d11: Add sideeffects/internal attributes to specs.

Don't defer arguments when functions fail.

d3dretrace: Basic d3d10 support.

d3dretrace: Add d3d9 prefix to d3d9 specific files.

d3d11: Trace initial data blobs.

d3d1x: Rename d3d10shader -> d3dcommonshader.