==========================
Intermediate mode examples
==========================

Basic concepts
==============

The HOOPS/3dAF distribution includes a variety of IM examples that show basic IM concepts. They are located in the *<hoops>/demo/common/standard* directory. 

*clip.c/objclip.c* - demonstrates user-defined clipping
 
*doily.c* - demonstrates overloading of the 'draw dc faces' callback point to do custom drawing

*lines.c/tracks.c* - demonstrates user-defined lines

*tristrip.c* - demonstrates overloading of 'draw 3d tristrips', 'draw 3d polyedges', and 'draw 3d polymarkers'


Complex clip regions
====================

When HOOPS/3dGS renders the scene, it creates an implicit window as discussed in the :doc:`Viewing > Windows section </prog_guide/3dgs/03_4_viewing_windows>`. This 'internal' HOOPS window defines a rectangular view, or clip region. It is sometimes desirable to define a non-rectangular viewport to provide a detail view. This is achieved by setting a user-defined clip region within an IM callback, and any geometry drawn while that region is active will be clipped to it. For example, if we wanted to have all the geometry underneath a driver instance clipped to a pentagon-shaped clip-region, we would set a draw_segment callback on the driver instance segment. The callback would look like the following:: 

	#define	SIDES	5
	#define DTR(x)	((x)*3.1415927/180.0)
	static	HT_Convex_Clip_Region	*ccr;
	static	HT_DC_Point				pent[256];


	void my_draw_segment (HIC_Rendition * nr, HIC_Segment_Info * si)
	{      
		HIC_Int_Rectangle CONST *rect = HIC_Show_Window_Extent(nr); 
		float cx = (float)0.5 * (rect->left + rect->right), cy = (float)0.5 * (rect->bottom + rect->top);
		float hw = (float)0.5 * (rect->right - rect->left), hh = (float)0.5 * (rect->top - rect->bottom);
		float rad = (float)0.75 * ((hw < hh) ? hw : hh);   
		int i;   
		
		/* define the convex clip region (a pentagon) */
		for (i=0; i < SIDES+1; i++)
		{
			pent[i].x = (float)(cx + rad * sin (DTR(360.0/SIDES*i)));
			pent[i].y = (float)(cy + rad * cos (DTR(360.0/SIDES*i)));
			pent[i].z = (float)0.0;
		}

		/* create the new clip region */
		ccr = HIC_New_Convex_Clip_Region (nr, SIDES, pent);
		
		/* set the clip region */
		HIC_Set_Convex_Clip_Region (nr, ccr);

		/* continue drawing; all geometry will be clipped against the pentagonal region */
		HIC_Draw_Segment (nr, si);

		/* free the clip region */
		HIC_Free_Convex_Clip_Region (ccr);
	}


Hardware acceleration
---------------------

HOOPS/3dGS will perform the complex clipping logic in software by default, but can take advantage of display hardware to accelerate this feature. Acceleration can be requested by setting the ''stencil' Driver_Option on the desired driver instance prior to it's first update. If a 'stencil' buffer is available, then the complex clipped scene will render more quickly at the cost of extra video memory usage. 
