Supplying A Frustrum

Contents

• 6.1 Introduction
• 6.2 What code do you need to supply?
  • 6.2.1 Required functionality
  • 6.2.2 Optional functionality
• 6.3 Registering the frustrum
• 6.4 File handling
  • 6.4.1 Structuring the file system for your application
  • 6.4.2 File types and file extensions
• 6.5 Memory management
• 6.6 Graphical output
  • 6.6.1 Calling PK rendering functions
  • 6.6.2 Supplying GO functions
  • 6.6.3 Choosing which graphics libraries to use
• 6.7 Error handling
  • 6.7.1 Handling failures with a non-zero error code
    • 6.7.1.1 Registering an error handler
  • 6.7.2 Handling failures with a zero error code
• 6.8 Starting and stopping a Parasolid session

[back to top]

6.1 Introduction

This chapter gives you an overview of what you need to do in order to integrate Parasolid into your application. It includes the following sections:

• “What code do you need to supply?”
• “Registering the frustrum”
• “File handling”
• “Memory management”
• “Graphical output”
• “Error handling”
• “Starting and stopping a Parasolid session”

[back to top]

6.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 required functionality of your application.

The use of the frustrum functions is explained in more detail in Section 6.4, “File handling”, Section 6.5, “Memory management”, and Section 6.6, “Graphical output” later on in this chapter.

6.2.1 Required functionality

You must provide the following frustrum functions:

6.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 initialise 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]

6.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 initialise 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 Section 9.2, “PK functions”.

PK_SESSION_frustrum_t fru; /* Declare fru as the frustrum */

PK_SESSION_frustrum_o_m( fru ); /* Initialise 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.

[back to top]

6.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 6.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.

For an example of this functionality, see the code example in the C++\Code Examples\Application support\Downward Interfaces\Frustrum folder, located in example_applications in your Parasolid installation folder.

6.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.

6.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

.xmm_txt

.xmm_bin

.M_T

.M_B

.sch_txt

.S_T

.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.

[back to top]

6.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.

See Section 9.3, “Memory management”, for more information on memory management.

[back to top]

6.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.

For an example of this functionality, see the code example in the C++\Code Examples\Application support\Downward Interfaces\Go folder, located in example_applications in your Parasolid installation folder.

6.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.

6.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 6.3, “Registering the frustrum” for details.

6.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]

6.7 Error handling

Parasolid errors can occur in a variety of situations. For example, if your application passes incorrect data to a PK function, or a PK function fails to complete an operation, Parasolid sends a non-zero error code to your application. In other situations, more details concerning the nature of the failure can be returned. In these situations, a value of zero is returned as the error code, and the information is sent back via a status code among the output arguments of the function.

6.7.1 Handling failures with a non-zero error code

There are two main decisions to make when deciding how to handle these errors:

• Whether your application should register an error-handling function with Parasolid
• Whether your application should use exceptions

Your application can write and register a particular function, known as an error handler, with Parasolid. This function will be called whenever an error occurs, to perform certain recovery tasks. Parasolid automatically invokes this error-handling function just before returning from a failing PK function, which means that the application does not have to deal with PK errors explicitly.

In addition, your application can choose whether to throw an exception when it encounters an error, via the try/throw/catch statements in C++ (or the equivalent setjmp/longjmp functions in C). This allows program execution to avoid some sections of code, and resume in a convenient place once the error has been dealt with. If your application uses a registered error handler combined with exceptions, it does not need to check the return status of each PK function before proceeding.

Whichever strategy you choose, the same recovery action needs to be taken at some point. This action depends on the severity of the error, as described in the following table:

6.7.1.1 Registering an error handler

You register an error-handling function with Parasolid by calling PK_ERROR_register_callbacks. Your error handler must receive a pointer to a PK_ERROR_sf_t structure and have the return type PK_ERROR_code_t, although it need not necessarily return a value, as this is not used by Parasolid. The PK_ERROR_sf_t structure contains details of the error such as the name of the failing function, the error code, and the severity of the error.

6.7.2 Handling failures with a zero error code

The documentation for each Parasolid function indicates whether it may return failure information through a status code, and if so, which variable contains the status code.

[back to top]

6.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 7.5, “Session parameters”.

You use the function PK_SESSION_stop to stop the Parasolid modeler.

[back to top]