Friday, July 02, 2004 |
GPC COM – Documentation
Contents:
1. General
2. Samples
3. API
5. Disclaimer
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/
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.
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 |
||||||||
|
clipOp As ClipOption – Type of clipping to perform. Can be one of the following values:
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. |
||||||||
|
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. |
||||||||
|
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. |
||||||||
|
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 |
|
A Read-Only property.
Returns an IGPC_VertexListCollection interface which is used to access contours of the polygon. |
|
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 |
|
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. |
|
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. |
|
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 |
|
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 |
|
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. |
|
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. |
|
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 |
|
A Read-Only property.
Returns number of IGPC_Vertex items in current collection. |
|
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. |
Version 2.31.0.6 |
First release – encapsulates GPC version 2.31 |
General Polygon Clipper Library
This software is Copyright © 1997-1999, Advanced
Interfaces Group, Department of Computer Science,
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 COM
Copyright © 2004 Tom Wolf - tom@www.aftershock.co.il
|