Friday, July 02, 2004

GPC COM – Documentation

The General Polygon Clipper COM Wrapper

Contents:

1. General

2. Samples

3. API

4. Release Notes

5. Disclaimer

General

The way I feel is that the GPC library is, also, a very powerful tool for polygon related researching and simulating (mathematics, graphics, games, geographic etc.). Therefore, there shouldn't be a reason that one won't be able to use GPC library in popular researching/simulating languages/environments.

The GPC COM wrapper encapsulates the GPC library with a thin/lightweight ActiveX component which implements the IDispatch interface. Because of this, it is now very easy to access GPC library technology via automation with any language/environment that supports this and still enjoy the performance.

Some of these are: VBScript/VBA, Javascript, Perl, Python, Visual Basic, MATLAB and more…

The GPC COM wraps the source code provided by Alan Murta's Generic Polygon Cipper Library found at:

http://www.cs.man.ac.uk/aig/staff/alan/software/

Samples

A few samples are provided with the GPC COM installation. Understanding these samples is the best way to understand the simple APIs of GPC COM.

The samples reside in the samples directory. For most samples to work, you need to save the polygon definition files, which can be found in the Polygons directory, to your local C:\ drive.

API

Getting started:

In order to use the GPC COM component, you must register (using regsvr32.exe) the GPCCOM.DLL file found in the BIN directory. This will register the component in the windows registry and will allow dynamic runtime access to the objects of the component via program IDs ("GPCCOM.GPC_Polygon") or GUIDs.

The APIs for GPC COM were designed to be simple and not to add any more functionalities than the original GPC Library exports.

The GPC COM component includes one COM Class (also referred to as CoClass) – GPC_Polygon, and four interfaces – IGPC_Polygon, IGPC_VertexListCollection, IGPC_VertexList, IGPC_Vertex.

Here is a picture of the GPC COM object model:

The following will describe each interface in details:

IGPC_Polygon – Interface to the GPC_Polygon CoClass which encapsulates the gpc_polygon structure.

This interface represents a Poly-Polygon (or multi-Polygon).

Methods:

Name

Parameters

Description

Clip

clipOp As ClipOption – Type of clipping to perform. Can be one of the following values:

0 -	clipDifference
1 -	clipIntersection
2 -	clipXOR
3 -	clipUnion

pPolygonClip As IGPC_Polygon – The other polygon (the clip polygon) used to clip with the current polygon.

Use this function to clip another polygon with the current polygon.

Return Value: On success, returns an IGPC_Polygon interface to a newly created polygon object which is the result of the clip operation.

ConvertToTristrip

None

Use this function to convert the current polygon to a tristrip representation of itself.

Return Value: On success, returns an IGPC_Polygon interface to a enwly created polygon object.

Load

strFilename As String – Destination filename.

[bReadHoles As Boolean = False] – Optional – whether or not to load hole indications from the polygon definition file. Using this flag as True means you must use the bReadHoles flag of the Save function.

Use this function to serialize the current polygon object.

Return Values: Returns True if succeeds else False.

Save

strFilename As String – Source filename.

[bWriteHoles As Boolean = False] – Optional – Whether or not to save hole indications of the polygon. Using this flag as True means you must use the bReadHoles flag of the Load function.

Use this function to load a polygon definition file to the current polygon object.

Return Values: Returns True if succeeds else False.

Properties:

Name

Description

Contours

A Read-Only property.

Returns an IGPC_VertexListCollection interface which is used to access contours of the polygon.

Tristrip

A Read-Only property.

Returns a Boolean value (True/False) indicating whether or not the current polygon object is a tristrip or not. Tristrip objects can not be clipped nor can they be serialized.

IGPC_VertexListCollection – Interface to an IGPC_VertexList collection which encapsulates an array of gpc_vertex_list structures.

The interface represents a collection of contours of a a Poly-Polygon (or multi-Polygon).

Methods:

Name	Parameters	Description
Add	None	Use this function to add a new contour (IGPC_VertexList) to the current polygon. Return Value: On success, this function returns an IGPC_VertexList interface to a newly created contour in the current interface.
Item	nIndex As Long	Use this function to access a specific IGPC_VertexList (contour) item in the collection. For your convenience, you may access each IGPC_VertexList item of this collection by using the For…Each…Next VB statements. Return Value: On success, returns an IGPC_VertexList item.
Remove	nIndex As Long	Use this function to remove a specific IGPC_VertexList item from the collection. Return Value: True if succeeds else False.

Properties:

Name

Description

Count

A Read-Only property.

Returns number of IGPC_VertexList items in current collection.

IGPC_VertexList – Interface to an IGPC_Vertex collection which encapsulates the gpc_vertex_list structure.

This interface represents a contour.

Methods:

Name	Parameters	Description
Add	dblX As Double – X value of the newly added vertex. dblY As Double – Y value of the newly added vertex.	Use this function to add a new vertex to the current vertex list collection (contour). Return Value: On success, returns an IGPC_Vertex interface.
Item	nIndex As Long	Use this function to access a specific IGPC_Vertex (vertex) item in the collection. For your convenience, you may access each IGPC_Vertex item of this collection by using the For…Each…Next VB statements. Return Value: On success, returns an IGPC_Vertex item.
Remove	nIndex As Long	Use this function to remove a specific IGPC_Vertex item from the collection. Return Value: True if succeeds else False.

Properties:

Name

Description

Count

A Read-Only property.

Returns number of IGPC_Vertex items in current collection.

Hole

A Read/Write property.

Sets or returns whether or not this contour is a hole of the polygon.

Note:

This value is used only as an indication of the Clip function. The clip function itself ignores this value on clipping.

IGPC_Vertex – Interface that encapsulates the gpc_vertex structure.

This interface represents a single vertex.

Properties:

Name

Description

A Read/Write property.

Set or returns X value of the current vertex.

A Read/Write property.

Set or returns Y value of the current vertex.

Release Notes

Version 2.31.0.6

First release – encapsulates GPC version 2.31

Disclaimer

General Polygon Clipper Library

This software is Copyright © 1997-1999, Advanced Interfaces Group, Department of Computer Science, University of Manchester. This software is free for non-commercial use. It may be copied, modified, and redistributed provided that the copyright notices which appear within the library source files are preserved on all copies. The intellectual property rights of the algorithms used reside with the University of Manchester Advanced Interfaces Group.

You may not use this software, in whole or in part, in support of any commercial product without the express consent of the author.

There is no warranty or other guarantee of fitness of this software for any purpose. It is provided solely "as is". Although no direct support for the use of this software will be given, bug reports may be sent to gpc@cs.man.ac.uk.

GPC COM

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the copyright notice which appear within the software and documentations appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation.

TOM WOLF DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL TOM WOLF BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.