AJA NTV2 SDK  18.0.0.2717
NTV2 SDK 18.0.0.2717
measure.h
Go to the documentation of this file.
1 //------------------------------------------------------------------------------
2 // File: Measure.h
3 //
4 // Desc: DirectShow base classes.
5 //
6 // Copyright (c) 1992-2001 Microsoft Corporation. All rights reserved.
7 //------------------------------------------------------------------------------
8 
9 
10 /*
11  The idea is to pepper the source code with interesting measurements and
12  have the last few thousand of these recorded in a circular buffer that
13  can be post-processed to give interesting numbers.
14 
15  WHAT THE LOG LOOKS LIKE:
16 
17  Time (sec) Type Delta Incident_Name
18  0.055,41 NOTE -. Incident Nine - Another note
19  0.055,42 NOTE 0.000,01 Incident Nine - Another note
20  0.055,44 NOTE 0.000,02 Incident Nine - Another note
21  0.055,45 STOP -. Incident Eight - Also random
22  0.055,47 START -. Incident Seven - Random
23  0.055,49 NOTE 0.000,05 Incident Nine - Another note
24  ------- <etc. there is a lot of this> ----------------
25  0.125,60 STOP 0.000,03 Msr_Stop
26  0.125,62 START -. Msr_Start
27  0.125,63 START -. Incident Two - Start/Stop
28  0.125,65 STOP 0.000,03 Msr_Start
29  0.125,66 START -. Msr_Stop
30  0.125,68 STOP 0.000,05 Incident Two - Start/Stop
31  0.125,70 STOP 0.000,04 Msr_Stop
32  0.125,72 START -. Msr_Start
33  0.125,73 START -. Incident Two - Start/Stop
34  0.125,75 STOP 0.000,03 Msr_Start
35  0.125,77 START -. Msr_Stop
36  0.125,78 STOP 0.000,05 Incident Two - Start/Stop
37  0.125,80 STOP 0.000,03 Msr_Stop
38  0.125,81 NOTE -. Incident Three - single Note
39  0.125,83 START -. Incident Four - Start, no stop
40  0.125,85 START -. Incident Five - Single Start/Stop
41  0.125,87 STOP 0.000,02 Incident Five - Single Start/Stop
42 
43 Number Average StdDev Smallest Largest Incident_Name
44  10 0.000,58 0.000,10 0.000,55 0.000,85 Incident One - Note
45  50 0.000,05 0.000,00 0.000,05 0.000,05 Incident Two - Start/Stop
46  1 -. -. -. -. Incident Three - single Note
47  0 -. -. -. -. Incident Four - Start, no stop
48  1 0.000,02 -. 0.000,02 0.000,02 Incident Five - Single Start/Stop
49  0 -. -. -. -. Incident Six - zero occurrences
50  100 0.000,25 0.000,12 0.000,02 0.000,62 Incident Seven - Random
51  100 0.000,79 0.000,48 0.000,02 0.001,92 Incident Eight - Also random
52  5895 0.000,01 0.000,01 0.000,01 0.000,56 Incident Nine - Another note
53  10 0.000,03 0.000,00 0.000,03 0.000,04 Msr_Note
54  50 0.000,03 0.000,00 0.000,03 0.000,04 Msr_Start
55  50 0.000,04 0.000,03 0.000,03 0.000,31 Msr_Stop
56 
57  WHAT IT MEANS:
58  The log shows what happened and when. Each line shows the time at which
59  something happened (see WHAT YOU CODE below) what it was that happened
60  and (if approporate) the time since the corresponding previous event
61  (that's the delta column).
62 
63  The statistics show how many times each event occurred, what the average
64  delta time was, also the standard deviation, largest and smalles delta.
65 
66  WHAT YOU CODE:
67 
68  Before anything else executes: - register your ids
69 
70  int id1 = Msr_Register("Incident One - Note");
71  int id2 = Msr_Register("Incident Two - Start/Stop");
72  int id3 = Msr_Register("Incident Three - single Note");
73  etc.
74 
75  At interesting moments:
76 
77  // To measure a repetitive event - e.g. end of bitblt to screen
78  Msr_Note(Id9); // e.g. "video frame hiting the screen NOW!"
79 
80  or
81 
82  // To measure an elapsed time e.g. time taken to decode an MPEG B-frame
83  Msr_Start(Id2); // e.g. "Starting to decode MPEG B-frame"
84  . . .
85  MsrStop(Id2); // "Finished MPEG decode"
86 
87  At the end:
88 
89  HANDLE hFile;
90  hFile = CreateFile("Perf.log", GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, 0, NULL);
91  Msr_Dump(hFile); // This writes the log out to the file
92  CloseHandle(hFile);
93 
94  or
95 
96  Msr_Dump(NULL); // This writes it to DbgLog((LOG_TRACE,0, ... ));
97  // but if you are writing it out to the debugger
98  // then the times are probably all garbage because
99  // the debugger can make things run awfully slow.
100 
101  A given id should be used either for start / stop or Note calls. If Notes
102  are mixed in with Starts and Stops their statistics will be gibberish.
103 
104  If you code the calls in upper case i.e. MSR_START(idMunge); then you get
105  macros which will turn into nothing unless PERF is defined.
106 
107  You can reset the statistical counts for a given id by calling Reset(Id).
108  They are reset by default at the start.
109  It logs Reset as a special incident, so you can see it in the log.
110 
111  The log is a circular buffer in storage (to try to minimise disk I/O).
112  It overwrites the oldest entries once full. The statistics include ALL
113  incidents since the last Reset, whether still visible in the log or not.
114 */
115 
116 #ifndef __MEASURE__
117 #define __MEASURE__
118 
119 #ifdef PERF
120 #define MSR_INIT() Msr_Init()
121 #define MSR_TERMINATE() Msr_Terminate()
122 #define MSR_REGISTER(a) Msr_Register(a)
123 #define MSR_RESET(a) Msr_Reset(a)
124 #define MSR_CONTROL(a) Msr_Control(a)
125 #define MSR_START(a) Msr_Start(a)
126 #define MSR_STOP(a) Msr_Stop(a)
127 #define MSR_NOTE(a) Msr_Note(a)
128 #define MSR_INTEGER(a,b) Msr_Integer(a,b)
129 #define MSR_DUMP(a) Msr_Dump(a)
130 #define MSR_DUMPSTATS(a) Msr_DumpStats(a)
131 #else
132 #define MSR_INIT() ((void)0)
133 #define MSR_TERMINATE() ((void)0)
134 #define MSR_REGISTER(a) 0
135 #define MSR_RESET(a) ((void)0)
136 #define MSR_CONTROL(a) ((void)0)
137 #define MSR_START(a) ((void)0)
138 #define MSR_STOP(a) ((void)0)
139 #define MSR_NOTE(a) ((void)0)
140 #define MSR_INTEGER(a,b) ((void)0)
141 #define MSR_DUMP(a) ((void)0)
142 #define MSR_DUMPSTATS(a) ((void)0)
143 #endif
144 
145 #ifdef __cplusplus
146 extern "C" {
147 #endif
148 
149 // This must be called first - (called by the DllEntry)
150 
151 void WINAPI Msr_Init(void);
152 
153 
154 // Call this last to clean up (or just let it fall off the end - who cares?)
155 
156 void WINAPI Msr_Terminate(void);
157 
158 
159 // Call this to get an Id for an "incident" that you can pass to Start, Stop or Note
160 // everything that's logged is called an "incident".
161 
162 int WINAPI Msr_Register(__in LPTSTR Incident);
163 
164 
165 // Reset the statistical counts for an incident
166 
167 void WINAPI Msr_Reset(int Id);
168 
169 
170 // Reset all the counts for all incidents
171 #define MSR_RESET_ALL 0
172 #define MSR_PAUSE 1
173 #define MSR_RUN 2
174 
175 void WINAPI Msr_Control(int iAction);
176 
177 
178 // log the start of an operation
179 
180 void WINAPI Msr_Start(int Id);
181 
182 
183 // log the end of an operation
184 
185 void WINAPI Msr_Stop(int Id);
186 
187 
188 // log a one-off or repetitive operation
189 
190 void WINAPI Msr_Note(int Id);
191 
192 
193 // log an integer (on which we can see statistics later)
194 void WINAPI Msr_Integer(int Id, int n);
195 
196 
197 // print out all the vaialable log (it may have wrapped) and then the statistics.
198 // When the log wraps you lose log but the statistics are still complete.
199 // hFIle==NULL => use DbgLog
200 // otherwise hFile must have come from CreateFile or OpenFile.
201 
202 void WINAPI Msr_Dump(HANDLE hFile);
203 
204 
205 // just dump the statistics - never mind the log
206 
207 void WINAPI Msr_DumpStats(HANDLE hFile);
208 
209 // Type definitions in case you want to declare a pointer to the dump functions
210 // (makes it a trifle easier to do dynamic linking
211 // i.e. LoadModule, GetProcAddress and call that)
212 
213 // Typedefs so can declare MSR_DUMPPROC *MsrDumpStats; or whatever
214 typedef void WINAPI MSR_DUMPPROC(HANDLE hFile);
215 typedef void WINAPI MSR_CONTROLPROC(int iAction);
216 
217 
218 #ifdef __cplusplus
219 }
220 #endif
221 
222 #endif // __MEASURE__
HANDLE
short HANDLE
Definition: ajatypes.h:338
Msr_Start
void WINAPI Msr_Start(int Id)
Msr_Stop
void WINAPI Msr_Stop(int Id)
Msr_Init
void WINAPI Msr_Init(void)
MSR_DUMPPROC
void WINAPI MSR_DUMPPROC(HANDLE hFile)
Definition: measure.h:214
Msr_Terminate
void WINAPI Msr_Terminate(void)
n
unsigned int n
Definition: pstream.cpp:148
Msr_Register
int WINAPI Msr_Register(__in LPTSTR Incident)
Msr_Control
void WINAPI Msr_Control(int iAction)
Msr_Integer
void WINAPI Msr_Integer(int Id, int n)
Msr_Reset
void WINAPI Msr_Reset(int Id)
Msr_Dump
void WINAPI Msr_Dump(HANDLE hFile)
Msr_Note
void WINAPI Msr_Note(int Id)
MSR_CONTROLPROC
void WINAPI MSR_CONTROLPROC(int iAction)
Definition: measure.h:215
Msr_DumpStats
void WINAPI Msr_DumpStats(HANDLE hFile)