Supplying A Frustrum

<<< Application Design

Chapters

The Example Application >>>

Contents

• 3.1 Introduction
• 3.2 What code do you need to supply?
  • 3.2.1 Required functionality
  • 3.2.2 Optional functionality
• 3.3 Registering the frustrum
• 3.4 File handling
  • 3.4.1 Structuring the file system for your application
  • 3.4.2 File types and file extensions
  • 3.4.3 Example file handling code
• 3.5 Memory management
• 3.6 Graphical output
  • 3.6.1 Calling PK rendering functions
  • 3.6.2 Supplying GO functions
  • 3.6.3 Choosing which graphics libraries to use
• 3.7 Error handling
  • 3.7.1 Choosing an error handling strategy
  • 3.7.2 Handling non-zero error codes
  • 3.7.3 What to do when an error occurs
• 3.8 Starting and stopping a Parasolid session

[back to top]

3.1 Introduction

As described in Chapter 2, "Application Design", you need to supply frustrum code to Parasolid in order to perform the following tasks:

• Frustrum control
• File (part data) handling
• Memory management
• Graphical output

This section gives you an overview of what you need to supply in order to accomplish these tasks.

[back to top]

3.2 What code do you need to supply?

This section outlines the frustrum functions that you need to supply in order to build a working frustrum. Some functions are optional; what you need to supply depends on the requred functionality of your application.

The use of the frustrum functions is explained in more detail in Section 3.4, "File handling", Section 3.5, "Memory management", and Section 3.6, "Graphical output" later on in this chapter.

[back to top]

3.2.1 Required functionality

You must provide the following frustrum functions:

[back to top]

3.2.2 Optional functionality

You can choose whether to implement the following frustrum functions. If you do not, they should be left as NULL. When you initialize the frustrum, all available functions are set to NULL, so you can effectively ignore any functions listed here that you don't require.

[back to top]

3.3 Registering the frustrum

Before you can start the modeler and make PK calls, you need to register the frustrum functions with Parasolid. To do this, use the PK function PK_SESSION_register_frustrum, which takes a list of pointers to the frustrum functions you have supplied.

You declare and initialize the frustrum in the same way that you set up any option structure in the PK. The following code extract shows how this might be done. For more details, refer to Appendix B, "Using the PK Interface".

PK_SESSION_frustrum_t fru; /* Declare fru as the frustrum */
PK_SESSION_frustrum_o_m( fru ); 
                     /* Initialize the frustrum functions */

/* Point to each of the frustrum functions you are supplying */

fru.fstart = MyAppStartFrustrum;
fru.fabort = MyAppAbortFrustrum;
fru.goopsg = MyAppOpenSeg;

/* Note: Many functions missing from the list above */

/* Register the frustrum with Parasolid */
PK_SESSION_register_frustrum( &fru ); 

In the code above, note that MyAppStartFrustrum represents a function that you have actually supplied a definition for, and fstart represents a field required by PK_SESSION_register_frustrum.

A specific example showing how the frustrum is registered in the Parasolid Example Application is described in Section 4.3, "The frustrum".

[back to top]

3.4 File handling

The files that Parasolid uses for storing part data are referred to as 'transmit' or 'XT' files. In order to transfer data through the frustrum, you need to write to and read from these files. Parasolid can also use several other file types, as described in Section 3.4.2, "File types and file extensions". You need to decide the format and location of these files in order to write your frustrum functions.

[back to top]

3.4.1 Structuring the file system for your application

You can configure Parasolid to handle many different kinds of archiving systems, such as:

• A controlled directory structure, in which part files are saved as individual files on the host computer, or
• A database that integrates Parasolid part files with application-specific information.

Your application should provide the following functionality for managing the files generated and required by Parasolid.

• Deleting parts from an archive.
• Keeping a record of, and listing, the keys used to archive parts, in the current session and in previous sessions.

The frustrum is passed a key (a text string) that identifies the part. This key can be used as a filename or as an index into the database, depending on the archiving system you have chosen.

[back to top]

3.4.2 File types and file extensions

Parasolid uses several file types, each of which can be written in one of the following formats:

• Neutral binary (recommended)
• Machine-dependent binary
• Text

At a minimum, your application must support Transmit files. Depending on its functionality, it may also need to deal with some of the other file types described here.

Each file type has a recommended file extension that is also dependent on the file system you are writing to or reading from, as shown in the table below. Note that file extensions ending in _t or _txt denote text-based formats, and extensions ending in _b or _bin denote binary-based formats.

.xmt_txt

.xmt_bin

.x_t 

.x_b

.sch_txt

.sch_bin

.s_t 

.s_b

.jnl_txt

.jnl_bin

.j_t 

.j_b

.snp_txt

.snp_bin

.n_t 

.n_b

.xmp_txt

.xmp_bin

.p_t 

.p_b

.xmd_txt

.xmd_bin

.d_t 

.d_b

The file handling functions in your frustrum must handle all the file types that you decide to support, adding the appropriate extensions. These functions may also test whether a file resides on a DOS style FAT device or a long filename NTFS type device before adding the extension, unless you decide to support only the FAT extensions, regardless of the filesystem. If you support both FAT and NTFS extensions, files can simply be renamed when transferring between the different systems. An example that shows how extensions can be added to filenames is described in Section 4.4.2, "File extensions" in Chapter 4, "The Example Application".

[back to top]

3.4.3 Example file handling code

Section 4.4, "File handling" gives details about how to implement file handling in the frustrum.

[back to top]

3.5 Memory management

You need to supply two memory management functions in the frustrum that allow Parasolid to allocate and free memory for its use. These functions control the way that memory is allocated to and freed for use in:

• Internal calculations
• Data structure storage

The memory management functions are FMALLO (allocate virtual memory) and FMFREE (free virtual memory).These functions map closely to the C functions malloc and free, and any function definitions you supply should be type-compatible with malloc and free.

You could consider implementing some buffering in order to improve performance compared to the standard functions. For example, with suitable definitions for FMALLO and FMFREE:

• Small amounts of memory (around 0.1 MBytes) could be served by a pool of memory set up by FSTART and managed by your application.
• Large amounts of memory (e.g. 1MB or more) could be requested from the operating system.

The memory management functions are registered when registering the frustrum.

A specific example showing how memory management functions are used in the Parasolid Example Application is described in Section 4.5, "Memory management".

[back to top]

3.6 Graphical output

If your application needs to display parts - whether by rendering them on screen, or printing them to a plotter or laser printer - you need to do three things:

• Call PK rendering functions to obtain the necessary information from Parasolid.
• Supply a set of functions known as the GO (Graphical Output) interface to interpret that information.
• Supply a graphics library that is used to render the parts on the appropriate device.

When a call is made to one of the PK rendering functions, the graphical data output by Parasolid is passed to the GO functions, which catch and interpret the data, filter it, and use the functionality of the graphics library to render the parts on the appropriate device.

[back to top]

3.6.1 Calling PK rendering functions

In order to render part data, your application needs to call a PK rendering function. There are three such functions available:

Each of these functions uses the supplied GO functions to pass graphical data to the appropriate graphics library.

The PK outputs graphical information in the form of segments. These correspond to identifiable portions of the model being rendered, and can be curves or facets (depending on the PK function used). There are two types of segments:

• Single-level segments, which contain data describing a curve or facet to be drawn.
• Hierarchical segments, which usually contain other hierarchical or single-level segments.

[back to top]

3.6.2 Supplying GO functions

Parasolid passes segment data to the GO functions. These functions use the supplied graphics libraries and may generate, for example, screen pictures, plot files and laser print files.

There are three GO functions in the frustrum. They all take the same arguments, but interpret them in different ways.

GO functions are registered together with the other frustrum functions. See the Section 3.3, "Registering the frustrum" for details.

A specific example showing how GO functions are defined in the Parasolid Example Application is described in Section 4.6, "Graphics".

[back to top]

3.6.3 Choosing which graphics libraries to use

Parasolid's graphical data output can be used in conjunction with many different graphical libraries. You must supply a graphics library for every device you want to use for rendering output. If your application renders to several different devices (for instance, it might render to the screen, and print paper copy), then you may need to supply several different libraries. You can write your own graphics libraries if you wish, or you can use third party libraries. The GOSGMT function calls the appropriate libraries in order to perform the necessary rendering.

[back to top]

3.7 Error handling

Parasolid can raise errors in a number of circumstances. For example, if your application passes incorrect data to a PK function, or a PK function fails in some way, then Parasolid raises an error. Your application needs to be able to handle these sorts of errors. This section describes how you go about doing this.

[back to top]

3.7.1 Choosing an error handling strategy

There are two approaches to handling errors from Parasolid.

• Your application can supply and register an error handler with Parasolid. This error handler is invoked when a PK function is about to return a failure. The error handler then takes the appropriate action.
• Your application can allow the PK function to complete, examine the returned value, and take appropriate action, usually by means of a wrapper function.

The strategy you choose probably depends on how errors are handled by the rest of your application. You are strongly recommended not to mix the two strategies, if this is possible.

Whichever strategy you choose, the same action needs to be taken. This action depends on the severity of the error, as supplied in the error call. See Section 3.7.3, "What to do when an error occurs" for more details.

Registering an error handler

You use PK_ERROR_register_callbacks to register an error handler with Parasolid. When a PK function is about to return an error, the error handler is passed a standard structure (PK_ERROR_sf_t) containing:

• The function returning the error
• The error severity
• The specific error code
• Other information to assist with isolating the problem

This data is always stored, and can be retrieved again if necessary using PK_ERROR_ask_last. The data for the last error can be cleared using PK_ERROR_clear_last.

You can see how an error handler is registered in the Parasolid Example Application in Section 4.7, "Error handling" in Chapter 4, "The Example Application".

[back to top]

3.7.2 Handling non-zero error codes

Every PK function returns an error code that indicates the result of the operation. If this value is zero - PK_ERROR_no_errors - the operation has completed successfully and your application can proceed.

However, if this value is non-zero, then the operation has failed to complete. Each numerical value indicates a predictable error, and your application must handle it appropriately:

• If your application uses a registered error handler, then the error handler must examine each return value and take suitable action.
• If your application does not use a registered error handler, then you must ensure the application itself examines each return value and takes appropriate action.

[back to top]

3.7.3 What to do when an error occurs

Whether you register an error handler or decide to handle each error explicitly in your application code, the action that needs to be taken when an error occurs is much the same.

The three error severity levels that your application has to manage are:

[back to top]

3.8 Starting and stopping a Parasolid session

You use the function PK_SESSION_start to start the Parasolid modeler. This takes an options structure that you can use to specify session specific options, as described in Section A.4, "Session parameters".

You use the function PK_SESSION_stop to stop the Parasolid modeler.

[back to top]