sampler.h
Namespaces:
namespace
The sampling framework.
Public Defines
define
SAMPLE(name, value)
define
SAMPLE_MATRIX(name, value) { \ ( name "/a1", value[ ( 0, 0 ) ] ); \ ( name "/a2", value[ ( 1, 0 ) ] ); \ ( name "/a3", value[ ( 2, 0 ) ] ); \ ( name "/a4", value[ ( 3, 0 ) ] ); \ ( name "/b1", value[ ( 0, 1 ) ] ); \ ( name "/b2", value[ ( 1, 1 ) ] ); \ ( name "/b3", value[ ( 2, 1 ) ] ); \ ( name "/b4", value[ ( 3, 1 ) ] ); \ ( name "/c1", value[ ( 0, 2 ) ] ); \ ( name "/c2", value[ ( 1, 2 ) ] ); \ ( name "/c3", value[ ( 2, 2 ) ] ); \ ( name "/c4", value[ ( 3, 2 ) ] ); \ ( name "/d1", value[ ( 0, 3 ) ] ); \ ( name "/d2", value[ ( 1, 3 ) ] ); \ ( name "/d3", value[ ( 2, 3 ) ] ); \ ( name "/d4", value[ ( 3, 3 ) ] ); \ }
define
SAMPLE_VECTOR(name, value) { \ ( name "/x", value.x ); \ ( name "/y", value.y ); \ ( name "/z", value.z ); \ }
Detailed Description
Public Defines
SAMPLE(name, value)
SAMPLE_MATRIX(name, value) { \ ( name "/a1", value[ ( 0, 0 ) ] ); \ ( name "/a2", value[ ( 1, 0 ) ] ); \ ( name "/a3", value[ ( 2, 0 ) ] ); \ ( name "/a4", value[ ( 3, 0 ) ] ); \ ( name "/b1", value[ ( 0, 1 ) ] ); \ ( name "/b2", value[ ( 1, 1 ) ] ); \ ( name "/b3", value[ ( 2, 1 ) ] ); \ ( name "/b4", value[ ( 3, 1 ) ] ); \ ( name "/c1", value[ ( 0, 2 ) ] ); \ ( name "/c2", value[ ( 1, 2 ) ] ); \ ( name "/c3", value[ ( 2, 2 ) ] ); \ ( name "/c4", value[ ( 3, 2 ) ] ); \ ( name "/d1", value[ ( 0, 3 ) ] ); \ ( name "/d2", value[ ( 1, 3 ) ] ); \ ( name "/d3", value[ ( 2, 3 ) ] ); \ ( name "/d4", value[ ( 3, 3 ) ] ); \ }
SAMPLE_VECTOR(name, value) { \ ( name "/x", value.x ); \ ( name "/y", value.y ); \ ( name "/z", value.z ); \ }
1 2//----------------------------------------------------------------------------- 3// Copyright (c) 2012 GarageGames, LLC 4// 5// Permission is hereby granted, free of charge, to any person obtaining a copy 6// of this software and associated documentation files (the "Software"), to 7// deal in the Software without restriction, including without limitation the 8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 9// sell copies of the Software, and to permit persons to whom the Software is 10// furnished to do so, subject to the following conditions: 11// 12// The above copyright notice and this permission notice shall be included in 13// all copies or substantial portions of the Software. 14// 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 21// IN THE SOFTWARE. 22//----------------------------------------------------------------------------- 23#ifndef _SAMPLER_H_ 24#define _SAMPLER_H_ 25 26#include "platform/types.h" 27 28/// The sampling framework. 29/// 30/// Sampling allows per-frame snaphots of specific values to be logged. For 31/// each value that you want to have sampled, you define a sampling key and 32/// then simply call the sample function at an appropriate place. If you 33/// want to sample the same value multiple times within a single frame, simply 34/// register several keys for it. 35/// 36/// The easiest way to use this facility is with the SAMPLE macro. 37/// 38/// @code 39/// SAMPLE( "my/sample/value", my.sample->val ); 40/// @endcode 41/// 42/// @section SamplerUsage Using the Sampler 43/// 44/// Before you use the sampler it is important that you let your game run for 45/// some frames and make sure that all relevant code paths have been touched (i.e. 46/// if you want to sample Atlas data, have an Atlas instance on screen). This 47/// will ensure that sampling keys are registered with the sampler. 48/// 49/// Then use the console to first enable the keys you are interested in. For 50/// example, to enable sampling for all Atlas keys: 51/// 52/// @code 53/// enableSamples( "atlas/*" ); 54/// @endcode 55/// 56/// Finally, you have to start the actual sampling. This is achieved with the 57/// beginSampling console function that takes a string informing the backend 58/// where to store sample data and optionally a name of the specific logging backend 59/// to use. The default is the CSV backend. In most cases, the logging store 60/// will be a file name. 61/// 62/// @code 63/// beginSampling( "mysamples.csv" ); 64/// @endcode 65/// 66/// To stop sampling, use: 67/// 68/// @code 69/// stopSampling(); 70/// @endcode 71/// 72/// @section Sample Keys 73/// 74/// Sample key name should generally follow the pattern "path/to/group/samplename". 75/// This allows to very easily enable or disable specific sets of keys using 76/// wildcards. 77/// 78/// Note that sampling keys are case-insensitive. 79 80namespace Sampler 81{ 82 void init(); 83 void destroy(); 84 85 void beginFrame(); 86 void endFrame(); 87 88 void sample( U32 key, bool value ); 89 void sample( U32 key, S32 value ); 90 void sample( U32 key, F32 value ); 91 void sample( U32 key, const char* value ); 92 93 inline void sample( U32 key, U32 value ) 94 { 95 sample( key, S32( value ) ); 96 } 97 98 /// Register a new sample key. 99 /// 100 /// @note Note that all keys are disabled by default. 101 U32 registerKey( const char* name ); 102 103 /// Enable sampling for all keys that match the given name 104 /// pattern. Slashes are treated as separators. 105 void enableKeys( const char* pattern, bool state = true ); 106}; 107 108#ifdef TORQUE_ENABLE_SAMPLING 109# define SAMPLE( name, value ) \ 110{ \ 111 static U32 key; \ 112 if( !key ) \ 113 key = Sampler::registerKey( name ); \ 114 Sampler::sample( key, value ); \ 115} 116#else 117# define SAMPLE( name, value ) 118#endif 119 120#define SAMPLE_VECTOR( name, value ) \ 121{ \ 122 SAMPLE( name "/x", value.x ); \ 123 SAMPLE( name "/y", value.y ); \ 124 SAMPLE( name "/z", value.z ); \ 125} 126 127#define SAMPLE_MATRIX( name, value ) \ 128{ \ 129 SAMPLE( name "/a1", value[ value.idx( 0, 0 ) ] ); \ 130 SAMPLE( name "/a2", value[ value.idx( 1, 0 ) ] ); \ 131 SAMPLE( name "/a3", value[ value.idx( 2, 0 ) ] ); \ 132 SAMPLE( name "/a4", value[ value.idx( 3, 0 ) ] ); \ 133 SAMPLE( name "/b1", value[ value.idx( 0, 1 ) ] ); \ 134 SAMPLE( name "/b2", value[ value.idx( 1, 1 ) ] ); \ 135 SAMPLE( name "/b3", value[ value.idx( 2, 1 ) ] ); \ 136 SAMPLE( name "/b4", value[ value.idx( 3, 1 ) ] ); \ 137 SAMPLE( name "/c1", value[ value.idx( 0, 2 ) ] ); \ 138 SAMPLE( name "/c2", value[ value.idx( 1, 2 ) ] ); \ 139 SAMPLE( name "/c3", value[ value.idx( 2, 2 ) ] ); \ 140 SAMPLE( name "/c4", value[ value.idx( 3, 2 ) ] ); \ 141 SAMPLE( name "/d1", value[ value.idx( 0, 3 ) ] ); \ 142 SAMPLE( name "/d2", value[ value.idx( 1, 3 ) ] ); \ 143 SAMPLE( name "/d3", value[ value.idx( 2, 3 ) ] ); \ 144 SAMPLE( name "/d4", value[ value.idx( 3, 3 ) ] ); \ 145} 146 147#endif // _SAMPLER_H_ 148