File: SCREENHookFunction.c

package info (click to toggle)
psychtoolbox-3 3.0.14.20170103%2Bgit6-g605ff5c.dfsg1-1
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 103,044 kB
  • ctags: 69,483
  • sloc: ansic: 167,371; cpp: 11,232; objc: 4,708; sh: 1,875; python: 383; php: 344; makefile: 207; java: 113
file content (348 lines) | stat: -rw-r--r-- 16,795 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
/*
	SCREENHookFunction.c	
  
    AUTHORS:
    
		Mario.Kleiner@tuebingen.mpg.de  mk
  
    PLATFORMS:	
	
		All.
    
    HISTORY:
    
		12/05/06	mk		Wrote it.
	
    DESCRIPTION:

		Manage special callback functions (processing hooks). Screen allows to "hook" specific
		OpenGL GLSL shaders, C callback functions or Matlab M-File functions into its internal
		processing chain at well defined points in a (hopefully) well defined manner. This allows
		to extend or customize Screens behaviour. Useful applications: Automatic transparent
		on-the-fly image processing on stimuli just before stimulus onset, e.g., filtering.
		Customization of drawing commands. Advanced stereo stimulus output algorithms. Support for
		special output devices like BrightSide HDR, Bits++, Pelli & Zhang attenuator..., interfacing
		with 3rd party hardware like trigger systems...
		
		We provide well defined hook points, each one with a unique descriptive name. Each hook is
		associated with a queue or chain of callback functions which is executed from the beginning
		to the end whenever that hook is processed. A callback can be a GLSL OpenGL shader program
		for image processing, a Matlab M-Function for high-level processing or a C callback function
		for complex low-level or realtime operations like triggering some output device or similar.
		
		This Screen subfunction provides subfunctions to add callbacks to the chain, reset the chain,
		enable or disable the chain, query properties of single hooks or dump the whole chain state
		to the command window for debug purpose.
  
    NOTES:

    TO DO:

*/

#include "Screen.h"

// If you change useString then also change the corresponding synopsis string in ScreenSynopsis.c
static char useString[] = "[ret1, ret2, ...] = Screen('HookFunction', windowPtr, 'Subcommand', 'HookName', arg1, arg2, arg3, arg4);";
//																		1           2             3          4     5     6     7
static char synopsisString[] = 
    "Manage Screen processing hook chains. Hook chains are a way to extend PTBs behaviour with plugins for generic processing or "
	"fast image processing. They should allow to interface PTB seamlessly with 3rd party special response collection devices or "
	"stimulus display devices. They also allow to perform high performance image processing, utilizing modern graphics hardwares "
	"huge computational bandwidth. Read 'help PsychGLImageProcessing' for more infos."
	"\n\n"
	"\nSubsubcommands and their syntax: \n\n"
	"Screen('HookFunction', [windowPtr], 'ListAll'); \n"
	"Print out a listing of all supported 'HookName' hook points, including a short synopsis on what they do, to the Matlab console "
	"in a human readable format - Useful as a reference for coding. "
	"The 'windowPtr' argument is optional. If left out (replaced by empty [] brackets) it prints all implemented chains."
	"\n\n"
	"[slot idstring blittercfg voidptr glslid luttexid insertString] = Screen('HookFunction', windowPtr, 'Query', hookname, slotnameOrIndex);\n"
	"Query information about a specific command slot in a specific hook processing chain: "
	"'hookname' is the name of the chain to query, e.g., 'StereoCompositingBlit' for the stereo processing chain. Use the subcommand "
	"'ListAll' for a printout of all available processing hooks and a short help on them. "
	"'slotnameOrIndex', either the symbolic name of the requested slot or the index in the hook-chain: Indices start with 0. Names can "
	"be assigned to slots when you add a processing slot with the 'Append' or 'Prepend' command, or they are system assigned names like "
	", e.g., 'StereoCompositingShader' for builtin shaders that are needed for stereo processing."
	"\n\n"
	"Return arguments, all optional: 'slot' is the index of the named slot in the chain to which the queried subfunction is assigned, or "
	"-1 if no such slot exists in the chain. 'glslid' numeric GLSL handle of the OpenGL GLSL shader object if the slot contains a "
	"GLSL shader for image processing on the GPU, 0 otherwise. 'luttexid' OpenGL texture handle of the first assigned lookup texture, "
	"0 if none assigned. 'voidptr' Memory pointer (encoded as double) to a C callback function, if one is assigned to this slot, 0 "
	"otherwise. 'blittercfg' either a parameter string with a meaning dependent of slot type, or the string 'NONE' if none assigned. "
	"'idstring' The symbolic name of this slot if any assigned, 'NONE' otherwise. 'insertString' the subcommand to use for reinserting "
	"this slot at the place it was after a deletion."
	"\n\n"
	"Screen('HookFunction', windowPtr, 'AppendShader', hookname, idString, glslid [, blittercfg] [luttexid1]); \n"
	"Append a new instruction slot to the end of hook processing chain 'hookname', assign the symbolic name 'idString' for later query "
	"by the 'Query' command. 'glslid' must be the name of a valid GLSL program object which defines the algorithm to apply on the GPU. "
	"'blittercfg' optional string with configuration commands for the shader. 'luttexid' Optional handle to an OpenGL texture which is "
	"used to encode lookup tables for the shader."
	"\n\n"
	"Screen('HookFunction', windowPtr, 'PrependShader', hookname idString, glslid [, blittercfg] [luttexid1]); \n"
	"Same as 'AppendShader' but add shader slot to beginning of the hook chain. It's recommended that you prepend slots instead of "
	"appending them, because PTB itself may add special slots at the end of a chain."
	"\n\n"
	"Screen('HookFunction', windowPtr, 'AppendCFunction', hookname, idString, voidfunctionptr); \n"
	"Screen('HookFunction', windowPtr, 'PrependCFunction', hookname, idString, voidfunctionptr); \n"
	"Attach a C callable function to the chain. voidfunctionptr is a double value which encodes a memory pointer to the function in "
	"memory. Encoding of the pointer and requirements to the function are non-trivial, so this is for expert developers only!"
	"\n\n"
	"Screen('HookFunction', windowPtr, 'AppendMFunction', hookname, idString, fevalstring); \n"
	"Screen('HookFunction', windowPtr, 'PrependMFunction', hookname, idString, fevalstring); \n"
	"Add a Matlab callable function to the chain. 'fevalstring' is the function call string: It will be passed to "
	"and evaluated by Matlabs or Octaves feval() function, so it has to work with that function. It is not allowed to "
	"return any return arguments. Some special names in the string will be replaced by PTB with internal settings, think "
	"of it as a macro replacement. Caution: The called function is not allowed to call any Screen() commands or you'll "
	"likely get undefined behaviour or a crash -- Screen is not reentrant!"
	"\n\n"
	"Screen('HookFunction', windowPtr, 'AppendBuiltin', hookname, idString, builtincmd); \n"
	"Screen('HookFunction', windowPtr, 'PrependBuiltin', hookname, idString, builtincmd); \n"
	"Add a call to a PTB built-in function 'builtincmd'."
	"\n\n"
	"You can also insert a hook function somewhere at a specific slot index via:\n"
	"Screen('HookFunction', windowPtr, 'InsertAtXXXYYY', ...);\n"
	"where XXX is a numeric slot id and YYY is the type specifier. Example: Insert a Builtin function\n"
	"at index 4 in hook 'UserDefinedBlit':\n"
	"Screen('HookFunction', windowPtr, 'InsertAt4Builtin', 'UserDefinedBlit', ...);\n"
	"\n\n"
	"Screen('Hookfunction', windowPtr, 'Remove', hookname, slotindex);\n"
	"Remove slot at index 'slotindex' in hookchain 'hookname'. The slot after this slot will move up by one.\n"
	"\n\n"
	"Screen('HookFunction', windowPtr, 'Enable', hookname); \n"
	"Screen('HookFunction', windowPtr, 'Disable', hookname); \n"
	"Enable or disable a specific hook chain. Chains are disabled until you enable them, with the exception of a few "
	"internal chains that get initialized and enabled by PTB itself, e.g., stereo algorithm chain. Disabled chains "
	"are not processed."
	"\n\n"
	"Screen('HookFunction', windowPtr, 'Reset', hookname); \n"
	"Reset a processing hook chain: All slots are deleted, resetting the chain to its startup state. Seldomly needed. "
	"\n\n"
	"Screen('HookFunction', windowPtr, 'Dump', hookname); \n"
	"Print out the full chain for hook 'hookname' to the Matlab console in a human readable format - Useful for debugging."
	"\n\n"
	"Screen('HookFunction', windowPtr, 'DumpAll'); \n"
	"Print out all chains for the given onscreen window 'windowPtr' to the Matlab console in a human readable format - Useful for debugging."
	"\n\n"
	"oldImagingMode = Screen('HookFunction', proxyPtr, 'ImagingMode' [, imagingMode]); \n"
	"Change or query imagingMode flags of provided proxy window 'proxyPtr' to 'imagingMode'. Proxy windows are used to define "
	"image processing operations, mostly for Screen('TransformTexture'). Returns old imaging mode."
	"\n\n"
	"General notes:\n\n"
	"* Hook chains are per onscreen window, so each window can have a different configuration and enable state.\n"
	"* Read all available documentation on the Psychtoolbox imaging pipeline in 'help PsychGLImageprocessing', the PsychDocumentation folder "
	"and on the Wiki before you make use of this function. Its way to complex to use it by guessing ;)\n";
	
static char seeAlsoString[] = "";

PsychError SCREENHookFunction(void) 
{
	PsychWindowRecordType	*windowRecord;
	char					numString[10];
	char					*cmdString, *hookString, *idString, *blitterString, *insertString;
	int						cmd, slotid, whereloc = 0;
	double					doubleptr;
	double					shaderid, luttexid1 = 0;

	blitterString = NULL;

    // All subfunctions should have these two lines.  
    PsychPushHelp(useString, synopsisString, seeAlsoString);
    if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none); };
    
    PsychErrorExit(PsychCapNumInputArgs(7));   	
    PsychErrorExit(PsychRequireNumInputArgs(2)); 	
    PsychErrorExit(PsychCapNumOutputArgs(7));  

    // Get the subcommand string:
	PsychAllocInCharArg(2, kPsychArgRequired, &cmdString);
	
	// Subcommand dispatcher:
	cmd=0;
	if (strstr(cmdString, "Append"))  { cmd=1; whereloc = INT_MAX; }
	if (strstr(cmdString, "Prepend")) { cmd=2; whereloc = 0; }	
	if (strcmp(cmdString, "Reset")==0)   cmd=3;
	if (strcmp(cmdString, "Enable")==0)  cmd=4;
	if (strcmp(cmdString, "Disable")==0) cmd=5;
	if (strcmp(cmdString, "Query")==0)   cmd=6;
	if (strcmp(cmdString, "Dump")==0)    cmd=7;
	if (strcmp(cmdString, "DumpAll")==0) cmd=8;
	if (strcmp(cmdString, "ListAll")==0) cmd=9;
	if (strcmp(cmdString, "Edit")==0)   cmd=10;
	if (strcmp(cmdString, "ImagingMode")==0) cmd=11;
	if (strstr(cmdString, "InsertAt")) { cmd=12; whereloc = -1; sscanf(cmdString, "InsertAt%i", &whereloc); }
	if (strstr(cmdString, "Remove")) cmd=13;
	
	if(cmd==0) PsychErrorExitMsg(PsychError_user, "Unknown subcommand specified to 'HookFunction'.");
	if(whereloc < 0) PsychErrorExitMsg(PsychError_user, "Unknown/Invalid/Unparseable insert location specified to 'HookFunction' 'InsertAtXXX'.");
	
	// Need hook name?
	if(cmd!=9 && cmd!=8 && cmd!=11) {
		// Get it:
		PsychAllocInCharArg(3, kPsychArgRequired, &hookString);
	}
	
    // Get the window structure for the onscreen window.
	windowRecord = NULL;
    PsychAllocInWindowRecordArg(1, (cmd!=9) ? TRUE : FALSE, &windowRecord);
    
	switch(cmd) {
		case 1:  // Append:
		case 2:  // Prepend:
		case 12: // Insert at location 'whereloc':
			// Add a new hook function callback to chain, either at beginning or end.
			
			// What type of callback/handler is to be added?
			if(strstr(cmdString, "Shader")) {
				// GLSL shader program object:
				
				// The id string:
				PsychAllocInCharArg(4, kPsychArgRequired, &idString);
				
				// The shader object handle:
				PsychCopyInDoubleArg(5, TRUE, &shaderid);

				// The blitter config string:
				PsychAllocInCharArg(6, FALSE, &blitterString);

				// (Optionally) a texture handle for a texture to attach to 2nd unit:
				PsychCopyInDoubleArg(7, FALSE, &luttexid1);
				
				// Add shader: 
				PsychPipelineAddShaderToHook(windowRecord, hookString, idString, whereloc, (unsigned int) shaderid, blitterString, (unsigned int) luttexid1);
			}
			else if(strstr(cmdString, "CFunction")) {
				// C callback function:

				// First the id string:
				PsychAllocInCharArg(4, kPsychArgRequired, &idString);
				
				// Then the void* to the function, encoded as a double value:
				PsychCopyInDoubleArg(5, TRUE, &doubleptr);
				
				// Add the function void* to the chain:
				PsychPipelineAddCFunctionToHook(windowRecord, hookString, idString, whereloc, PsychDoubleToPtr(doubleptr));
				
			}
			else if(strstr(cmdString, "MFunction")) {
				// Matlab/Octave/Whatever runtime environment callback function:

				// First the id string:
				PsychAllocInCharArg(4, kPsychArgRequired, &idString);
				
				// Then the call string (for feval()) for the function:
				PsychAllocInCharArg(5, TRUE, &blitterString);
				
				// Add the function to the chain:
				PsychPipelineAddRuntimeFunctionToHook(windowRecord, hookString, idString, whereloc, blitterString);
				
			}
			else if(strstr(cmdString, "Builtin")) {
				// Built in special function:

				// First the id string:
				PsychAllocInCharArg(4, kPsychArgRequired, &idString);
				
				// Then the options-string:
				PsychAllocInCharArg(5, TRUE, &blitterString);
				
				// Add the function to the chain:
				PsychPipelineAddBuiltinFunctionToHook(windowRecord, hookString, idString, whereloc, blitterString);				
			}
			else {
				// Unknown?!?
				PsychErrorExitMsg(PsychError_user, "Unknown callback type specified to 'HookFunction'.");
			}
		break;
		
		case 3: // Reset hook-chain:
			PsychPipelineResetHook(windowRecord, hookString);
		break;

		case 4: // Enable hook-chain:
			PsychPipelineEnableHook(windowRecord, hookString);
		break;

		case 5: // Disable hook-chain:
			PsychPipelineDisableHook(windowRecord, hookString);
		break;
		
		case 6: // Query properties of a slot in a specific hook-chain:
			// Get the id string:
			if (PsychGetArgType(4)!=PsychArgType_char) {
				// No id string provided: Try to get numeric slot id and
				// turn it into an id string:
				PsychCopyInIntegerArg(4, TRUE, &slotid);
				sprintf(numString, "%i", slotid);
				idString = (char*) &numString[0];
				slotid = -1;
			}
			else {
				PsychAllocInCharArg(4, TRUE, &idString);
			}
			
			// Query everything that's there and copy it out:
			slotid = PsychPipelineQueryHookSlot(windowRecord, hookString, &insertString, &idString, &blitterString, &doubleptr, &shaderid, &luttexid1);
			
			// Copy out all infos:
			PsychCopyOutDoubleArg(1, FALSE, slotid);
			PsychCopyOutCharArg(2, FALSE, (idString) ? idString : "NONE");
			PsychCopyOutCharArg(3, FALSE, (blitterString) ? blitterString : "NONE");
			PsychCopyOutDoubleArg(4, FALSE, doubleptr);
			PsychCopyOutDoubleArg(5, FALSE, shaderid);
			PsychCopyOutDoubleArg(6, FALSE, luttexid1);
			PsychCopyOutCharArg(7, FALSE, (insertString) ? insertString : "NONE");
		break;

		case 7: // Dump specific hook-chain:
			PsychPipelineDumpHook(windowRecord, hookString);
		break;

		case 8: // Dump all hook-chains:
			PsychPipelineDumpAllHooks(windowRecord);
		break;
		
		case 9: // List all hook-chains:
			PsychPipelineListAllHooks(windowRecord);
		break;
		
		case 10: // Set properties of a slot in a specific hook-chain:
			// Get the id string:
			PsychAllocInCharArg(4, kPsychArgRequired, &idString);
			
			// Query everything that's there and copy it out:
			slotid = PsychPipelineQueryHookSlot(windowRecord, hookString, &insertString, &idString, &blitterString, &doubleptr, &shaderid, &luttexid1);
			
			if (slotid<0)  PsychErrorExitMsg(PsychError_user, "In 'Edit' No such hook slot in that hook chain for that object.");
			// Copy out all infos:
			PsychCopyOutDoubleArg(1, FALSE, slotid);
			PsychCopyOutCharArg(2, FALSE, (idString) ? idString : "NONE");
			PsychCopyOutCharArg(3, FALSE, (blitterString) ? blitterString : "NONE");
			PsychCopyOutDoubleArg(4, FALSE, doubleptr);
			PsychCopyOutDoubleArg(5, FALSE, shaderid);
			PsychCopyOutDoubleArg(6, FALSE, luttexid1);
		break;

		case 11: // Change imagingMode flags for a proxy window:
			if (windowRecord->windowType!=kPsychProxyWindow) PsychErrorExitMsg(PsychError_user, "In 'ImagingMode' Invalid windowPtr provided. Must be a proxy window!");
			PsychCopyOutDoubleArg(1, FALSE, (double) windowRecord->imagingMode);
			
			luttexid1 = -1;
			PsychCopyInDoubleArg(3, FALSE, &luttexid1);
			if (luttexid1 < 0 && luttexid1!=-1) PsychErrorExitMsg(PsychError_user, "In 'ImagingMode' Invalid imagingMode flags provided. Must be positive!");
			if (luttexid1!=-1) {
				windowRecord->imagingMode = (unsigned int) luttexid1;
			}
		break;
		
		// case 12 see at top.
		
		case 13: // Remove slot at given index.
			PsychCopyInIntegerArg(4, TRUE, &slotid);
			PsychPipelineDeleteHookSlot(windowRecord, hookString, slotid);
		break;
	}
	
    // Done.
    return(PsychError_none);
}