Main Page   Modules   Class Hierarchy   Compound List   File List   Compound Members   File Members   Related Pages  

PolygonShape Class Reference

Represents a shape consisting of polygons. More...

#include <PolygonShape.h>

List of all members.

Public Methods

Constructing/Destructing
overloaded operators
Non-Isomorph manipulations
Isomorph mainpulations
information retrieval
state history

Private Attributes

data structures
state variables

Detailed Description

An instance of this class holds informations about a set of nodes, and their connections among each other.

Note:
I did a moreless complete rewrite after beeing completly pissed off by all the fuzz about pointer/refferences to Nodes and their (in)consistense.

A node consists of a VECTOR3D describing the nodes position in 3-D space, along with an integer key to identify the node. Keys are unique, meaning in one shape there can not exist more then one node with the same key. Node to key bindings are guarantied to remain consistend as long as the instance lives. A key is guarantied to remain valid, unless the corresponding node is deleted.

An edge is internaly represented by a pair of keys, that identify the nodes, connected by the edge. Nevertheless, you con check out edges of type Edge (including position informations) for conveniance.

See also:
PolygonShape::getEdge(int)

The only way to add nodes/edges to a shape is by adding edges. Removal of edges or nodes is both possible although it should be noted that a node is deleted automaticaly if it isn't connected to any other point after the removal of an edge/node. Also, of cause, edges are deleted if one of the nodes they connect is deleted. As a result, you won't find invalid edges or non-connected nodes within a PolygonShape.

All modifications to the node positions are done solely by this class. There is no way of doing this from outside. PolygonShape comes with a somewhat high-level interface for modifying node positions. it implements a selection model, which basicaly is a subset of the shape's nodes. In this selection, together with the node's keys, their position at the time of selecting is stored. Selected nodes may be transformed by applying a a affine transformation to them

See also:
PolygonShape::applyTransformation(float * , bool)

To make undos easier, i have added a state history. it is simply a double linked list of PolygonShape instances which can be used to save or load the complete state of a shape. since we don't have to bother about pointer consitency anymore, this is pretty easy. (YES! I'M INVINCIBLE!! ;-)))
Note:
IMPORTANT: For this trick to work, it is essential, that both operator= and operator== aswell as the copy constructor ignore the member field mStates. So it's not that i've forgotten something in this methods, i left it out on purpose!! To make you understand why this is neccessary, just imagine what would happen if you add it in there: Each time you save a PolygonShape, its mStates field is saved as well, meaning each PolygonShape in this list is duplicated which again will duplicate its mStates member and so on. This all would leave you with over-exponential space requirements and you sure don't want that!


Constructor & Destructor Documentation

PolygonShape::PolygonShape ( )
 

Does nothing but create an empty Shape

PolygonShape::PolygonShape ( const PolygonShape & original )
 

creates a new shape which is equal to the original. The state of the original is completle reasambled, apart of the mStates member. Please have a look at the notes above!

PolygonShape::~PolygonShape ( )
 

Frees all memory occupied by the shape and all of its members


Member Function Documentation

PolygonShape & PolygonShape::operator= ( const PolygonShape & original )
 

Completely reasamble the state of original in this shape, but ignoring the mStates member. See node above!

int PolygonShape::operator== ( PolygonShape & other )
 

Not too much of a usefull function, since it does not check for graph isomorphism (which is a realy nasty job, NP-complete, i think) but simply tests all the member fields for equality. To be honest, i don't give a fuck about how usefull this is. It's just to comply with the requirements of a "nice" class i read somewhere. To meet this requirements, all we have to do is make sure, that a=b makes a equal to b in respect to this operator.

See also:
operator=(PolygpnShape &)

int PolygonShape::continueStrip ( VECTOR3D next )
 

Adds an edge from the last node (returned by getLastNode()) to next If there is no last node (because the shape is empty) no edge is added Instead startStrip(VECTOR3D) is called with next as parameter

Parameters:
next   the next point to be included into the strip. A new node with this position will be added to the strip, no matter if there is allready a node at this position or not. If you want to include a existing node into the strip, use continueStrip(int)
Returns:
the key of the added Node or -1 if the shape was empty.

int PolygonShape::continueStrip ( int key )
 

Adds an edge from the last node (returned by lastNode() to next If there is no last node (because the shape is empty) no edge is added Instead startStrip(int) is called with next as parameter

Parameters:
key   the key of the next point in the strip.
Returns:
key if the node was added or -1 if key wasn't found.

int PolygonShape::startStrip ( int key )
 

Tells the Shape that you are about to draw a new strip of Edges starting from the node identified by key

Note:
Also note that the next call of getLastNode() will return key, or -1 if key wasn't found
Parameters:
key   the key of the node at which the strip should be started
Returns:
key, or -1 if key wasn't found

int PolygonShape::startStrip ( VECTOR3D first )
 

Tells the Shape that you are about to draw a new strip of Edges

Note:
first is not appended to the shape's list of nodes until you actualy call continueStrip. Also note that the next call of lastnode will return -1;
Parameters:
first   the position at which you want to start the strip. Once you actualy create a line with a subsequent call to continueStrip, a new node with position first will be added to the shape, no matter if there is allready a node at this position or not. If you want to use a existing node to start a strip, use startStrip(int).
Returns:
-1 by definition, since there is no node added yet and thus a key can not be returned. Of cause one can argue if it would have been nicer to make this method void. Well not that important anyway. ;-)

void PolygonShape::removeEdge ( int a,
int b )
 

Note:
if one of the points is not connected to any other point after the removal of this edge, this point is removed.

void PolygonShape::removeNode ( int key )
 

removes a node from the shape by deleting all edges, that hold a reference to key

Note:
be aware of the fact, that this might imply the removal of adjacent nodes.
Parameters:
key   the key of the node you want to delete

void PolygonShape::select ( int key )
 

this is done by adding its key/position pair to the selection. If key is not found no action is taken

Parameters:
key   the key of the node you want to select

void PolygonShape::unselect ( int key )
 

this is done by removing its key/position pair from the selection. If key is not found in the selection, no action is taken

Parameters:
key   the key of the node you want to unselect

void PolygonShape::clearSelection ( )
 

marks all nodes as not selected by removing all keys/position pairs from the selection.

void PolygonShape::selectAll ( )
 

marks all nodes as selected by adding them to the selection

void PolygonShape::selectRegion ( VECTOR3D first,
VECTOR3D second )
 

Parameters:
first   the first corner of the rectangle, i.e. upper-left
second   the second corner of the rectangle, i.e. lower-right

void PolygonShape::selectRegion ( VECTOR3D first,
float qradius )
 

Parameters:
first   the center of the circle/sphere
qradius   the radius of the circle/sphere. this should be the maximal quadratic distance from center a point may have to become selected.

void PolygonShape::applyTransformation ( float * matrix,
bool absolute = false )
 

You can use this method in two ways:

  • to transform the selected nodes by using their current positions
  • to do the same thing in respect to the positions saved in the selection.
    Note:
    the second variant comes in very handy if you want to realize coninous transformation while avoiding dead spots, where the transformation becomes non-injective. To ship around this singularities, you can first update the selection (using updateSelection()) and then do multible transformations all relative to the positions in the selection. PolygonShapeEditor makes extensive use of this feature.
    Parameters:
    matrix   should be a 4x4 matrix, stored line after line.
    absolute   if this flag is set, transformation accures relative to the positions saved in the selection.

void PolygonShape::updateSelection ( )
 

Update the positions saved in the selection to the corresponding current positions of the selected nodes.

See also:
applyTransformation(float * , bool)

vector< pair< int, int > > PolygonShape::adjacentEdges ( int key )
 

Use this method to get a vector filled with all edges that refer to key</key>. @node the return type vector<pair<int,int> > can mostly be used as any standard array type in C.

Parameters:
key   the key of the node you want to get adjacent lines to.
Returns:
a vector storing values of type pair<int,int> which represents the adjacent edges.

pair< int, int > PolygonShape::getPair ( int index )
 

Get a pair of keys to nodes representing an edge

Parameters:
index   the index of the edge
Returns:
a pair<int,int> containing the keys to the nodes the edge connects

Edge PolygonShape::getEdge ( int index )
 

Parameters:
index   the index of the edge
Returns:
the Edge at index index

VECTOR3D PolygonShape::getNode ( int key )
 

Parameters:
key   the key that identifies the node.
Returns:
the position of the node identified by key if key is not found, a dummy is returned (0,0,0) Not very sensible but what should i do.

int PolygonShape::indexOf ( pair< int, int > edge )
 

Parameters:
edge   a pair<int,int> containing the keys to the nodes that are connected by edge.
Returns:
the index of an edge equal to edge or -1 if no such edge exists.

int PolygonShape::indexOf ( int a,
int b )
 

See also:
indexOf(pair<int,int>)

pair< int, int > PolygonShape::getLastEdge ( )
 

Returns:
a pair of key to the nodes connected by the edge that was last added to the shape

int PolygonShape::getLastKey ( )
 

Returns:
the key of the last Node inserted into a strip this maybe -1 in which case the node isn't checked in jet. To retrieve the position anyway,use getLastNode()

VECTOR3D PolygonShape::getLastNode ( )
 

Returns:
the position of the last node inserted into a strip. this node maybe already contained in the shape. If this is true, you can get its key with getLastKey()

int PolygonShape::findNearestNode ( VECTOR3D point )
 

Parameters:
point   the position at which to look for a node
Returns:
the key of the node closest to the given position.

bool PolygonShape::isSelected ( int key )
 

Parameters:
key   the key of the node you want to check
Returns:
true if key is in the selection.

map< int, VECTOR3D > PolygonShape::getSelection ( )
 

Returns:
a map<int,VECTOR3D> containing all key/position pairs that are in the selection.
Note:
remember that the positions in the returned map are those stored in the selection and will propably differ from the current position of the nodes.
See also:
applyTransformation(float * ,bool)

map< int, VECTOR3D > PolygonShape::getNodes ( )
 

Returns:
a map<int,VECTOR3D> containing the keys of all Nodes and their current positions

int PolygonShape::save ( )
 

Saves the current state of this shape to the mStates list.

Returns:
the number of saved states after insertion.
See also:
revert()

int PolygonShape::revert ( )
 

Reverts the state of this Shape to the last state saved in mStates and removes it from the history

Returns:
the number of saved states after removal of the last one or -1 if there is no state to revert to.


Member Data Documentation

vector< pair< int, int > > PolygonShape::mEdges [private]
 

The Vector does the (de-)allocation of all memory needed for our Edges We let it initaly allocate mem for 3 elements

list< PolygonShape *> PolygonShape::mStates [private]
 

a list of PolygonShapes, each representing the state of this PolygonShape at a certain point in time. this has to be a list of pointers to avoid recursive data structure

VECTOR3D PolygonShape::mLastNode [private]
 

It is possible, that this node is allready in this shape. In this case mLastKey is the key to it.

int PolygonShape::mLastKey [private]
 

Holds the key to the last node inserted into a strip, or -1, if that node did not belong to the shape yet.

int PolygonShape::mNextKey [private]
 

The next key to be used when a node is added to mNodes.

Note:
DO NOT EVEN THINK of doing something other than incrementing to this key. OK, constructors and the like don't count. But after that, the only assignment operator i want to see behind mNextKey is '++' ! Did i make myself clear enough? i hope so.

bool PolygonShape::mHaveStart [private]
 

This flag should usualy be set, if it's possible to continue drawing a strip. This means, startStrip has been called at least once.


The documentation for this class was generated from the following file:
Generated at Fri Apr 19 16:53:06 2002 for GLFramework by doxygen1.2.6 written by Dimitri van Heesch, © 1997-2001