HookRetrace

Calls the specified function everytime an R ("Special: Retrace" layer in MapEd3) is hit in the renderstring (curmap.rstring). For example, if your renderstring is "1,E,2,R", every time the 'R' is rendered, the function you specified in this hook will be called.

HookRetrace's frequency of calling varies from system to system and game to game. If person a is getting 40 frames per second, the hooked function will be called 40 times a second for them. If another person gets 80 frames per second, that person's hooked function will be called 80 times a second. It is this behavior that makes HookRetrace ideal for anything that depends specifically on how many Render() calls get made by the engine. Anyone needing a more consistant timer should look into HookTimer.

It is critical to remember that HookRetrace carries over between maps. If your HookRetrace calls a function defined within a map, and then you load a different map, it will attempt to continue to call that function in the new map. If the new map does not have a function by that name, it with exit with an error about "VC sys script out of bounds". Unless you have the same function defined in several maps, you must make sure to unload the function from retrace before switching maps. Do this with HookRetrace(""); before any rendering on the 2nd map is done.

Note: A map must be active for HookRetrace() to have an effect.

// Assume that this function exists somewhere in the system code.
void TintScreen() 
{
    ColorFilter(CF_GREY, screen );
}

// Assume this line is in your map's startup function.
HookRetrace( "TintScreen" );

/*
	Now, when the map with the preceding line is run, what happens depends on 
	its renderstring.

	Since the function is only called when an 'R' is hit in the string, if your string 
	was "1,E,2,R", everything would be grayscale since it was applied after 
	everything else was rendered.

	However, if the renderstring was "1,2,R,E" the map would be grayscale, and the 
	entities on the map would be in color.  (This is how Paladin's Quest did their 
	flashbacks, for an obscure reference.)

	If your rstring was "1,E,R,2", then layer 1 and the entities would be gray, and 
	tile layer 2 would be in it's original colors.  See how it works?

	Finally, if the rstring had no 'R' in it at all, like "1,E,2", then the function specified
	in HookRetrace would never be called!
*/