How To Add To Screen.rtf	

PLATFORMS:
	
Only OS X for now.
    
AUTHORS:
	
Allen.Ingling@nyu.edu		awi 

HISTORY:

10/11/04	awi		
-Created. 

1/08/05		awi		
-Merged in Keith Schneder's corrections.  
-Converted to .rtf from .h file.  The rtf editor autowraps lines and spellchecks while typing,  correct behavior for editing documentation.
-Fixed formatting, enhanced comments.

1/11/05		awi
- Removed step to add yourself as a screen author.  I can do that when I merge contributions into the master copy.     

DESCRIPTION:
	
The Psychtoolbox Screen command passes control to a Screen subfunction which is specified when invoking Screen.  For example, Screen('OpenWindow',..) passes control to a C function which opens an onscreen window.   This documents  explains how to extend Screen by adding your own subfunctions.  

Screen is used by programs written in the MATLAB language, but Screen itself and it's subfunctions are written in C.  This document assumes knowledge of C but no prior experience with Xcode.
		
Don't be intimidated by the number of steps listed here; We give details on how to control the Xcode interface which makes this explanation long in words though it is uncomplicated.

ACKNOWLEDGMENTS:

Keith Schneider suggested corrections and additions.    

INSTRUCTIONS TO CREATE A NEW SCREEN SUBFUNTION:
   
Steps to create a new Screen subfunction:

1. Make sure you are using XCode version 1.5 or greater.  

2. Launch the Xcode Psychtoolbox project by double clicking on the file "Psychtoolbox3/Projects/MacOSX/Psychtoolbox/PsychToolbox.pbproj".

3. Select the Screen project from the Active Target drop down menu in Xcode.

4. From the Xcode view menu on the menu bar select "toggle embedded editor".  Xcode is easier to use when the embedded editor is turned on but by default it is turned off.

5. Choose a name for your new screen subfunction.  From that name derive name of the C function which implements your new screen subfuction, and the name of the C file which will contain that function .   Construct the mame of your new C function by prefixing the name of your Screen subfunction with "SCREEN".  For example, if you were creating a new SCREEN subfunction named "DrawCube", invoked from within MATLAB by "Screen('DrawCube', ...)", then you should name your C function "SCREENDrawCube" and you should have named the C file which contains it
"SCREENDrawCube.c".   

6. Create the C file for the source to your subfunction.  Place it in Psychtoolbox3/Source/Common/Screen.  The easiest way to locate the Psychtoolbox3/Source/Common/Screen folder is to right-click/control-click on a Screen subfunction, for example "SCREENClose.c", and choose "Reveal in Finder".  The easiest way to create a C file is to duplicate and rename an existing file already in the Psychtoolbox3/Source/Common/Screen folder.  
  
7. Add your new C file to the Screen target by dragging it from the OS X Finder into Xcode's Screen file sources list in the "Groups & Files Pane".  C files for new Screen commands belong in alphabetical under: Psychtoolbox/Psychtoolbox Source/Mex Targets/Screen/Sources/Subcommands

After dragging your new file from the Finder to the Xcode Groups & Files pain, Xcode will present a dialog box.  In that dialog box select the Screen target from the list of targets and deselect any other targets.  Make the file reference relative to target.  Do not select the option to copy files into folder.  Click the "Add" button to accept settings and make the dialog go away.

8. Click on your new file in the Groups & Files list to display it in the Xcode embedded editor.  (If the file does not appear in the embedded editor, that might be because the embedded editor is turned off.  To turn on the embedded editor, select "Toggle Embedded Editor" from the Xcode "View" menu.)

9. In your C file, create the comments header at the top of file.  Please use the format of prexisting Psychtoolbox comment headers as provided, for example, CloseAll.c: 

	/*
		SCREENCloseAll.c		
	  
		AUTHORS:
		
			Allen.Ingling@nyu.edu		awi 
	  
		PLATFORMS:	
			
			Only OS X for now.

		HISTORY:
			
			01/23/02	awi		Wrote It.
			10/12/04	awi		Changed "SCREEN" to "Screen" and "Close" to "CloseAll" in useString .

		DESCRIPTION:
		
			Closes all open onscreen windows, offscreen windows, and textures.  
	 
		T0 DO:
		
		BUGS:
	 
	*/

10. In your C file, #include "Screen.h"

	#include "Screen.h" 

11. In your C file, define variables useString, synopsisString and seeAlsoString.  For example, in CloseAll.c:

	static char useString[] = "Screen('CloseAll');";
	static char synopsisString[] = 
		"Close all open onscreen and offscreen windows and textures";  
	static char seeAlsoString[] = "OpenWindow, OpenOffscreenWindow";

11.5 Add the useString from step 11 to the ScreenSynopsis.c file.  Screen, when called with no arguments, gives a synopsis of itself, displaying useStrings for each of its subfunctions.  When screen displays it's own synopsis it gets useStrings for subfunctions from ScreenSynopsis.c.  For example, the CloseAll synopsis string in ScreenSynopsis.c looks like this:

	synopsis[i++] = "Screen('CloseAll');";  
 
12. In your C file, define the C subfunction which will be called when your function is invoked from MATLAB.  Refer to step 4 for how to name your C function. Note:  Arguments declared in your C function header are not the arguments which will be passed between your Screen subfunction and the MATLAB environment.  Your new C function should return type PsychError and accept type void.  For example, here is the function definition for SCREENCloseAll.

	PsychError SCREENCloseAll(void)
	{
	...
      }

13. Within your new C function, register the help strings which you defined in step 10.  If your funcctions registers help strings, then Screen will automatically display your help strings in the MATLAB command window under appropriate circumstances.        

	PsychPushHelp(useString, synopsisString, seeAlsoString);
	
14. When a Screen subcommand is invoked with a traling question mark, it displays a help string in the MATLAB command window.  To detect if your C function has been invoked with the question mark and then issue help, include the following line:

	if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
   	 
15. In your C file, Add the following line to the end of your new C function:

    return(PsychError_none);	
		
16. In your C file, to test that you have installed your file correctly into the screen project, add the following line:
		
	printf("Hello World!\n");
		
17. Add the function prototype for your new C function to Screen.h.  For example, here is the function prototype for the Screen CloseAll C function:

	PsychError	SCREENCloseAll(void);				

18. Register your new function with Screen by adding a registration call to RegisterProject.c.  RegisterProject.c is located in the Groups&File pane of the Psychtolbox Xcode project under Psychtoolbox/Psychtoolbox Source/Mex Targets/Screen/Sources/Common.  

The form of the registration call should be:

		PsychErrorExit(PsychRegister("YourFunctionName", &SCREENYourFunctionName));
		
YourFunctionName is the string passed to Screen in MATLAB to invoke your function. SCREENYourFunctionName in the name of the new C function which you are adding to the Screen project. For example, CloseAll is registered like this:

		PsychErrorExit(PsychRegister("CloseAll",  &SCREENCloseAll)); 

IMPORTANT:  Every mex target has its own Register.c file.  Make sure that when you add your file name to Register.c that add it only to Screen's Register.c file and not some other target's Register.c.  This is easy to get right if you locate Register.c by expanding Screen folders in Xcode's Groups & Files pane.  D not try to locate source files in the OS X finder.  

19. Build Screen.  Note that the Xcode project automatically copies the new version of Screen into the Psychtoolbox PsychBasic folder located in the Psychtoolbox source tree at Psychtoolbox3/Target/OSX/Psychtoolbox/PsychBasic.  Your MATLAB path should this copy of the Psychtoolbox.  In case you have previously downloaded the Psychtoolbox without the source, remove that copy of the Psychtoolbox from your MATLAB path and use only the copy included in the PsychSource.      

20. In MATLAB, flush the the old version of Screen from MATLAB memory so that MATLAB uses your new version of Screen:

	>> clear mex
	>> 
	
21.  In MATLAB, invoke your new Screen sufunction to test that it has been added the project correctly.

	>> Screen('YourFunctionName');
	Hello World!
	>> 

22. If step 19 works, then fill in your new C function.  Note that the Psychtoolbox defines C functions for reading and returning Screen arguments.  These have not been documented, but