Sampler

The sampling framework.

Public Functions

void

beginFrame()

void

destroy()

void

enableKeys(const char * pattern, bool state)

Enable sampling for all keys that match the given name pattern.

void

endFrame()

void

init()

U32

registerKey(const char * name)

void

sample(U32 key, bool value)

void

sample(U32 key, const char * value)

void

sample(U32 key, F32 value)

void

sample(U32 key, S32 value)

void

sample(U32 key, U32 value)

Detailed Description

The sampling framework.

Sampling allows per-frame snaphots of specific values to be logged. For each value that you want to have sampled, you define a sampling key and then simply call the sample function at an appropriate place. If you want to sample the same value multiple times within a single frame, simply register several keys for it.

The easiest way to use this facility is with the SAMPLE macro.

SAMPLE( "my/sample/value", my.sample->val );

Using the Sampler

Before you use the sampler it is important that you let your game run for some frames and make sure that all relevant code paths have been touched (i.e. if you want to sample Atlas data, have an Atlas instance on screen). This will ensure that sampling keys are registered with the sampler.

Then use the console to first enable the keys you are interested in. For example, to enable sampling for all Atlas keys:

   enableSamples( "atlas/*" );
*

Finally, you have to start the actual sampling. This is achieved with the beginSampling console function that takes a string informing the backend where to store sample data and optionally a name of the specific logging backend to use. The default is the CSV backend. In most cases, the logging store will be a file name.

beginSampling( "mysamples.csv" );

To stop sampling, use:

stopSampling();

Keys

Sample key name should generally follow the pattern "path/to/group/samplename". This allows to very easily enable or disable specific sets of keys using wildcards.

Note that sampling keys are case-insensitive.

Public Functions

beginFrame()

destroy()

enableKeys(const char * pattern, bool state)

Enable sampling for all keys that match the given name pattern.

Slashes are treated as separators.

endFrame()

init()

registerKey(const char * name)

note:
Note that all keys are disabled by default.

sample(U32 key, bool value)

sample(U32 key, const char * value)

sample(U32 key, F32 value)

sample(U32 key, S32 value)

sample(U32 key, U32 value)