14. How To Tutorial # 2: How & why to install the custom handlers functions

One of the finer points of writing a full-featured NuGraf program is installing the following three custom handler functions:

1. The Custom Error Handler receives informational, error and fatal error messages from the renderer and acts upon them accordingly. If a fatal error is reported then this handler should be modified so that it jumps back to the main event handler in your application. Any informational messages received by this routine should be presented to the user for interactive feedback. If this handler is not installed then all error messages will be printed to STDOUT, and fatal errors will cause the program to abort prematurely.
   
   
2. The Custom Interrupt Handler is called once scanline and performs two functions. First, it receives status information from the renderer which indicates how much of the image has been rendered; this information can be displayed for immediate user feedback. Second, the status returned from the handler to the renderer can be used to prematurely abort the rendering process; this allows for a quick and easy method for the user to abort the renderer. If this handler is not installed then no mechanism will exist to abort a rendering.
   
   
3. The Custom Confirmation Handler allows a user to confirm potentially non-reversible events, such as the overwriting of a file, or asking whether a shadow map image should be computed. If this handler is not installed then the renderer will assume that it is ok to proceed with the desired action.

You can also find working examples of these custom handlers in the 'userio.c' file located in the 'examples/ascii' sub-directory contained in the NuGraf distribution files. Another set of handlers are available in the 'examples/windows' sub-directory which work within a Microsoft Windows application.