The Example Application

<<< Supplying A Frustrum

Chapters

Further Implementation Decisions >>>

Contents

• 4.1 Building and running the Example Application
• 4.2 Calling PK functions
• 4.3 The frustrum
• 4.4 File handling
  • 4.4.1 File types
  • 4.4.2 File extensions
• 4.5 Memory management
• 4.6 Graphics
• 4.7 Error handling
• 4.8 Starting the Parasolid session

To complement the overview of frustrum implementation in Chapter 3, "Supplying A Frustrum", this chapter describes a simple Parasolid-powered application whose source code you are free to examine. The Parasolid Example Application described here is provided on the Parasolid CD for PC platforms.

The Example Application is a Windows NT application that demonstrates how to combine the various components necessary into a working application. As well as providing a simple frustrum, it shows you how to make calls to PK functions, and can be used in a limited way to prototype PK function calls. Because it is designed specifically to demonstrate all the components of a Parasolid-powered system, it may not necessarily reflect the optimal design for your application.

The application is written in Microsoft Visual C++ and uses Microsoft Foundation Classes. It was compiled and built using Microsoft Visual C++ Version 6. It uses the OpenGL graphics library for displaying part models.

The compiled application can be run on Windows NT4, Windows 2000, and 95/98.

Full documentation for the Example Application is provided in the manual Using the Example Application.

[back to top]

4.1 Building and running the Example Application

The Parasolid CD contains the complete set of files necessary to examine, build, and run the Example Application using Microsoft Visual C++ running under Windows NT 4 or 2000. To build and run the Example Application:

• Place the Parasolid CD into the CD-ROM drive on your computer.
• Use an archiving application such as WinZip to extract the file
  X :\Example_Application\ExampleApp.zip to a folder on your local hard disk (where X represents the name of your CD-ROM drive).
• To load the Example Application into Visual C++, double-click the file
  Source\Example App.dsw in the folder that you extracted application to.
• Press Ctrl+F5 to build the Example Application and run it. Follow any prompts from Visual C++ to build the necessary files.

The Example Application has a single window that contains a menu bar, toolbar, and a viewing area that is initially empty.

Figure 4-1 The Example Application

If the PK calls in the code you are testing are written as a series of steps, then click to execute each step in turn, examining the output along the way. See Section 4.2, "Calling PK functions", for details about structuring code this way.

[back to top]

4.2 Calling PK functions

To make use of Parasolid functionality in the Example Application, you add PK function calls to the CMyCode class; specifically, to the function CMyCode::RunMyCode. This function is reserved for PK function calls so that you can evaluate Parasolid functionality easily. You can find the definition for this function in the file MyCode.cpp.

You can add code that is structured as a single step, or as multiple steps using a case statement. When running code that contains multiple steps, click the button in the Example Application to execute the next step. The following example shows a case statement that consists of two steps: a block is drawn in the first step, and a cylinder is drawn in the second step.

int CMyCode::RunMyCode(int step)
{
	
// The code below is sample code. On exiting the function 
// the bodies that exist are drawn 
	
	static PK_BODY_t block;
	static PK_BODY_t cylinder;
	CString text;
	BOOL finished = FALSE;

	switch( step )
	{
	case 1:
  
/*   Create a block
     Size: 10 x 10 x 10.
     Location & orientation: default (pass NULL 
     as pointer to the basis_set argument).
*/
  
		PK_BODY_create_solid_block
                 ( 10.0, 10.0, 10.0, NULL, &block );
		break;

	case 2:

	/* Create a cylinder
	Radius: 2.5
	Height: 20.0
	Location & orientation: default.  */
  
		PK_BODY_create_solid_cyl
                 ( 2.5, 20.0, NULL, &cylinder );
		break;

	default:
		finished = 1;
	}
	return finished;
}

The model display is updated in the viewing area of the Example Application whenever:

• CMyCode::RunMyCode completes an additional step (if PK code uses a case statement).
• CMyCode::RunMyCode finishes executing (if PK code doesn't use a case statement).
• You click one of the buttons in the Example Application's toolbar.

When the display is updated, the Example Application checks for new parts in the session and re-facets or re-renders according to the selected display type.

[back to top]

4.3 The frustrum

The Example Application uses a very simple frustrum that is set up and initialized by functions in the CSession class (see the file session.cpp).

The CSession::Start function sets up and registers the frustrum, initializing further functions that are needed for opening, closing, reading and writing files.

The sequence of events involved in setting up and registering the frustrum is as follows:

• A frustrum is declared, and then initialized using a macro.
• All the required frustrum functions are declared.
• The frustrum is registered using PK_SESSION_register_frustrum.

[back to top]

4.4 File handling

File handling in the Example Application is very straightforward. The application does not use its own database; it only uses Parasolid data files when reading and storing part information.

The following frustrum functions are used for file handling:

• OpenReadFrustrumFile (FFOPRD)
• OpenWriteFrustrumFile (FFOPWR)
• CloseFrustrumFile (FFCLOS)
• ReadFromFrustrumFile (FFREAD)
• WriteToFrustrumFile (FFWRIT)

You can find the definitions for all these functions in the file frustrum.cpp, or listed under the Globals definitions in the ClassView tab of the Workspace window in Visual C++.

[back to top]

4.4.1 File types

The Example Application supports a subset of the file types described in the section Section 3.4.2, "File types and file extensions". In particular, delta files are not supported, because no rollback mechanism has been implemented.

Journal files are supported, but only when journaling is switched on when setting up and starting the modeler, as described in Section A.4, "Session parameters".

[back to top]

4.4.2 File extensions

The Example Application uses three character extensions for all file types. Attaching the correct file extension for a given type of file is a two-stage process:

• Determine the file type to use, and attach the first part of the file extension.
• Determine the file format to use (text or binary), and attach the last part of the file extension.

These stages are performed by the filetype_guise_string and filetype_format_string functions, respectively. Both these functions return pointers to the relevant parts of the extension. You can find both of these functions in frustrum.cpp.

Both of these functions are called by the FFOPRD and FFOPRW frustrum functions. Other frustrum functions used for file handling access the pointer values returned by these functions directly.

[back to top]

4.5 Memory management

The memory handling functions supplied to Parasolid are defined in CSession::Start and registered along with other frustrum functions (see the file session.cpp). These functions, GetMemory (FMALLO) and ReturnMemory (FMFREE), enable Parasolid to request and relinquish memory. They make use of the "new" and "delete" operators in C++.

The Example Application manages all the memory associated with entities in the session, freeing memory when it becomes available. However, it does not free any output arrays that have been allocated in CRunMyCode, so you should take care to free memory that is no longer needed when adding functions to CRunMyCode. For example, if your code calls

PK_BODY_ask_faces(body, nfaces, faces)

then you need to free the returned faces array yourself.

See Appendix B, "Using the PK Interface" for information on how to do this.

[back to top]

4.6 Graphics

The Example Application uses the OpenGL graphics library, and makes calls to it when starting up the application and when drawing parts. The display is set up by CExampleAppView::InitOpenGL (in the file OpenGl.cpp), which initializes colors, pixel format, projection matrices, model matrices, and lights.

The relevant graphics functions are registered with Parasolid in the function CExampleAppDoc::OnNewDocument (in the file 'Example AppDoc.cpp'). This registers the following functions to frustrum functions that handle graphical output:

• CopenSegment (GOOPSG)
• CcloseSegment (GOCLSG)
• CoutputSegment (GOSGMT)

The definitions of each of these functions can be found in GO.cpp.

As well as opening, closing, and outputting graphical segments supplied by Parasolid, they also set appropriate colors and material properties using various calls to Parasolid and OpenGL. The data is filtered to deal with displaying lines, circles, ellipses and facets separately, and then the appropriate OpenGL function called.

[back to top]

4.7 Error handling

The Example Application takes a simple approach to handling Parasolid errors; a function called CSession::PKerrorHandler is registered with Parasolid as an error handler, and this is called whenever an error is returned.

The error handler takes the character string corresponding to the error and displays this on the screen in a standard Windows message box. No corrective action is performed.

The error handler is defined and registered in the CSession::Start function (session.cpp).

[back to top]

4.8 Starting the Parasolid session

The Parasolid modeler is started towards the end of the call to CSession::Start (session.cpp). This is done using the PK_SESSION_start function, which uses an options structure in the normal way.

If required, specific session options can be set between the macro call and the function call. See Section A.4, "Session parameters" for more details.

[back to top]