plane

plane — Adds capabilities to draw and handle planes.

Synopsis

#define             PLANE_TYPE
#define             PLANE                               (obj)
#define             PLANE_CLASS                         (klass)
#define             IS_PLANE_TYPE                       (obj)
#define             IS_PLANE_CLASS                      (klass)
#define             PLANE_GET_CLASS                     (obj)
typedef             PlaneClass;
                    Plane;
GType               plane_get_type                      (void);
enum                Plane_hidingMode;
#define             PLANE_SIDE_PLUS
#define             PLANE_SIDE_MINUS
#define             PLANE_SIDE_NONE
Plane*              planeNew                            (float vertices[8][3],
                                                         float vect[3],
                                                         float dist,
                                                         ToolColor *color);
Plane*              planeNew_undefined                  (void);
gboolean            planeSet_normalVector               (Plane *plane,
                                                         float vect[3]);
gboolean            planeSet_distanceFromOrigin         (Plane *plane,
                                                         float dist);
gboolean            planeSet_color                      (Plane *plane,
                                                         ToolColor *color);
void                planeSet_box                        (Plane *plane,
                                                         float vertices[8][3]);
int                 planeShowHide                       (Plane *plane,
                                                         VisuData *visuData,
                                                         gboolean hide,
                                                         float side);
void                planeDraw                           (Plane *plane);
void                planeGet_basis                      (Plane *plane,
                                                         float xyz[2][3],
                                                         float center[3]);
GList*              planeGet_intersection               (Plane *plane);
float*              planeGet_reducedIntersection        (Plane *plane,
                                                         guint *nVals);
void                planeGet_nVectUser                  (Plane *plane,
                                                         float *vect);
void                planeGet_nVect                      (Plane *plane,
                                                         float *vect);
void                planeGet_distanceFromOrigin         (Plane *plane,
                                                         float *dist);
void                planeGet_color                      (Plane *plane,
                                                         ToolColor **color);
int                 planeSet_hiddenState                (Plane *plane,
                                                         int side);
int                 planeGet_hiddenState                (Plane *plane);
int                 planeSet_rendered                   (Plane *plane,
                                                         gboolean rendered);
gboolean            planeGet_rendered                   (Plane *plane);
gboolean            planeGet_cross                      (Plane *plane,
                                                         float pointA[3],
                                                         float pointB[3],
                                                         float *lambda);
void                planesDraw_list                     (Plane **list,
                                                         int openGLId);
int                 planeShowHide_all                   (VisuData *visuData,
                                                         Plane **listOfPlanes);
gboolean            planesGet_visibility                (Plane **listOfPlanes,
                                                         float point[3]);
gboolean            planesGet_intersection              (Plane **listOfPlanes,
                                                         float pointA[3],
                                                         float pointB[3],
                                                         float inter[3],
                                                         gboolean inside);
gboolean            planesGet_orderedIntersections      (int nPlanes,
                                                         Plane **listOfPlanes,
                                                         float pointA[3],
                                                         float pointB[3],
                                                         float *inter,
                                                         int *index);
int                 planeSet_hidingMode                 (Plane_hidingMode mode);
gboolean            planesParse_XMLFile                 (gchar *filename,
                                                         Plane ***list,
                                                         GError **error);
gboolean            planesExport_XMLFile                (gchar *filename,
                                                         Plane **list,
                                                         GError **error);

Object Hierarchy

  GObject
   +----Plane

Signals

  "moved"                                          : Run Last / No Recursion / No Hooks

Description

A Plane is a GObject. It is defined by its normal vector and the distance of the plane with the origin (see planeSet_normalVector() and planeSet_distanceFromOrigin()). When these informations are given and an VisuOpenGLView is used to render the plane, V_Sim computes the intersections of the plane with the bounding box (see planeGet_intersection()).

Planes can be used to hide nodes defining their planeSet_hiddenState() and planeSet_hidingMode(). A list of planes can also be exported or imported from an XML file using planesExport_XMLFile() and planesParse_XMLFile().

Planes can have transparency but the support of it is limited to one plane. If several planes are drawn with transparency, they may hide each other because of the implementation of transparency in OpenGL (planes are treated as single polygons).

Details

PLANE_TYPE

#define PLANE_TYPE	     (plane_get_type ())

return the type of Plane.


PLANE()

#define PLANE(obj)	     (G_TYPE_CHECK_INSTANCE_CAST(obj, PLANE_TYPE, Plane))

Cast the given obj into Plane type.

obj :

a GObject to cast.

PLANE_CLASS()

#define PLANE_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST(klass, PLANE_TYPE, PlaneClass))

Cast the given klass into PlaneClass.

klass :

a GObjectClass to cast.

IS_PLANE_TYPE()

#define IS_PLANE_TYPE(obj)    (G_TYPE_CHECK_INSTANCE_TYPE(obj, PLANE_TYPE))

Test if the given ogj is of the type of Plane object.

obj :

a GObject to test.

IS_PLANE_CLASS()

#define IS_PLANE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE(klass, PLANE_TYPE))

Test if the given klass is of the type of PlaneClass class.

klass :

a GObjectClass to test.

PLANE_GET_CLASS()

#define PLANE_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS(obj, PLANE_TYPE, PlaneClass))

It returns the class of the given obj.

obj :

a GObject to get the class of.

PlaneClass

typedef struct PlaneClass_struct PlaneClass;

An opaque structure.


Plane

typedef struct _Plane Plane;

All fields are private, use the access routines.


plane_get_type ()

GType               plane_get_type                      (void);

This method returns the type of Plane, use PLANE_TYPE instead.

Returns :

the type of Plane.

enum Plane_hidingMode

typedef enum
  {
    plane_hideUnion,
    plane_hideInter,
    plane_nbHidingMode
  } Plane_hidingMode;

Enum used to address different hiding modes. See planeSet_hidingMode() for further details.

plane_hideUnion

element are masked if one plane at least mask it ;

plane_hideInter

element are masked if all planes mask it ;

plane_nbHidingMode

number of masking possibilities.

PLANE_SIDE_PLUS

#define PLANE_SIDE_PLUS +1

This is a key that defines which side is hidden by the plane. For this value, the side is the one pointed by the normal vector.


PLANE_SIDE_MINUS

#define PLANE_SIDE_MINUS -1

This is a key that defines which side is hidden by the plane. For this value, the side is the one at the opposite of the one pointed by the normal vector.


PLANE_SIDE_NONE

#define PLANE_SIDE_NONE 0

This is a key that defines which side is hidden by the plane. For this value, no node is hidden.


planeNew ()

Plane*              planeNew                            (float vertices[8][3],
                                                         float vect[3],
                                                         float dist,
                                                         ToolColor *color);

Create a plane with the specified attributes.

vertices :

the coordinates that describes the rendering box ;

vect :

three values defining the normal vector (unitary or not) ;

dist :

the distance between origin and intersection of the plane and the line made by origin and normal vector ;

color :

a ToolColor.

Returns :

a newly allocated Plane structure.

planeNew_undefined ()

Plane*              planeNew_undefined                  (void);

Create a new plane with default values. This plane can't be rendered directly and one needs to computes its intersection with the bounding box before using planeComputeInter().

Returns :

a newly allocated Plane structure.

planeSet_normalVector ()

gboolean            planeSet_normalVector               (Plane *plane,
                                                         float vect[3]);

Change the normal vector defining the orientation of the plane.

plane :

a Plane object ;

vect :

three values defining the normal vector (unitary or not).

Returns :

1 if the intersections should be recalculated by a call to planeComputeInter(), 0 if not. Or -1 if there is an error.

planeSet_distanceFromOrigin ()

gboolean            planeSet_distanceFromOrigin         (Plane *plane,
                                                         float dist);

Change the position of the plane.

plane :

a Plane object ;

dist :

the distance between origin and intersection of the plane and the line made by origin and normal vector.

Returns :

1 if the intersections should be recalculated by a call to planeComputeInter(), 0 if not. Or -1 if there is an error.

planeSet_color ()

gboolean            planeSet_color                      (Plane *plane,
                                                         ToolColor *color);

Change the color of the plane.

plane :

a Plane object ;

color :

a ToolColor.

Returns :

0 if everything went right.

planeSet_box ()

void                planeSet_box                        (Plane *plane,
                                                         float vertices[8][3]);

This method is used to fit plane in a box for rendering purpose. It also computes the intersections between the bounding box and the plane.

plane :

a Plane ;

vertices :

the vertices that describe the rendering box.

Since 3.6


planeShowHide ()

int                 planeShowHide                       (Plane *plane,
                                                         VisuData *visuData,
                                                         gboolean hide,
                                                         float side);

A call to this method change the visibility flag of all nodes of the given VisuData. Notice that this method makes a call to visu_data_createAllNodes if necessary.

plane :

a Plane ;

visuData :

a VisuData which show or hide nodes to;

hide :

a boolean, TRUE to hide elements, FALSE to return them to visibility ;

side :

give a positive number to hide elements in the same side that the normal vector, a negative number will hide the other nodes.

Returns :

1 if the calling method should ask for redraw, 0 otherwise.

planeDraw ()

void                planeDraw                           (Plane *plane);

Call OpenGL primitives to draw the plane.

plane :

a Plane.

planeGet_basis ()

void                planeGet_basis                      (Plane *plane,
                                                         float xyz[2][3],
                                                         float center[3]);

Stores the coordinates of barycentre of the plane in center and provide coordinates of two orthogonal vector in the plane. The planeComputeInter() should have been called before.

plane :

a Plane ;

xyz :

two vectors.

center :

a point in cartesian coordinates.

planeGet_intersection ()

GList*              planeGet_intersection               (Plane *plane);

The list of intersection between the plane and the box is made of float[3]. The planeComputeInter() should have been called before.

plane :

a Plane.

Returns :

a list of float[3] elements. This list is owned by V_Sim.

planeGet_reducedIntersection ()

float*              planeGet_reducedIntersection        (Plane *plane,
                                                         guint *nVals);

This routine returns the coordinates in the plane basis set of its intersections with a box (see planeSet_box()). The coordinates are appended in the return array which length is stored in nVals.

plane :

a Plane object.

nVals :

a location for an integer.

Returns :

a newly allocated array of nVals * 2 values. Free it with g_free().

Since 3.6


planeGet_nVectUser ()

void                planeGet_nVectUser                  (Plane *plane,
                                                         float *vect);

Stores the coordinates of the normal vector in vec of the plane. It returns the values given by the user, not the normalized vaues.

plane :

a Plane.

vect :

an already alloacted (size 3) float array.

planeGet_nVect ()

void                planeGet_nVect                      (Plane *plane,
                                                         float *vect);

Stores the coordinates of the normal vector in vect of the plane. It returns the normalized values.

plane :

a Plane.

vect :

an already alloacted (size 3) float array.

planeGet_distanceFromOrigin ()

void                planeGet_distanceFromOrigin         (Plane *plane,
                                                         float *dist);

Stores the distance of the plane to the origin.

plane :

a Plane ;

dist :

a float location to store the value.

planeGet_color ()

void                planeGet_color                      (Plane *plane,
                                                         ToolColor **color);

Stores the color of the plane.

plane :

a Plane ;

color :

a ToolColor pointer location to store the value.

planeSet_hiddenState ()

int                 planeSet_hiddenState                (Plane *plane,
                                                         int side);

The plane can hide the nodes on one of its side. The side argument can be PLANE_SIDE_PLUS or PLANE_SIDE_MINUS or PLANE_SIDE_NONE. It codes the side of the plane which hides the nodes. If PLANE_SIDE_NONE is selected all nodes are rendered.

plane :

a Plane ;

side :

a key, PLANE_SIDE_NONE, PLANE_SIDE_PLUS or PLANE_SIDE_MINUS.

Returns :

1 if planeShowHide_all() should be called.

planeGet_hiddenState ()

int                 planeGet_hiddenState                (Plane *plane);

The plane can hide the nodes on one of its side. this method get the status for the given plane.

plane :

a Plane.

Returns :

the state, defined by PLANE_SIDE_PLUS or PLANE_SIDE_MINUS or PLANE_SIDE_NONE.

planeSet_rendered ()

int                 planeSet_rendered                   (Plane *plane,
                                                         gboolean rendered);

Change the visibility of the plane.

plane :

a Plane ;

rendered :

TRUE to make the plane drawable.

Returns :

1 if planeShowHide_all() should be called.

planeGet_rendered ()

gboolean            planeGet_rendered                   (Plane *plane);

Get the visibility of a plane.

plane :

a Plane.

Returns :

TRUE if the plane is visible.

planeGet_cross ()

gboolean            planeGet_cross                      (Plane *plane,
                                                         float pointA[3],
                                                         float pointB[3],
                                                         float *lambda);

Given the line [AB], it looks for an intersection with plane. If lambda is provided, it gives the position of the intersection (lambda = 0 means A, lambda = 1 means B).

plane :

a Plane object.

pointA :

a point.

pointB :

another point.

lambda :

a location to store a float (can be NULL).

Returns :

TRUE if any crossing point is found.

Since 3.6


planesDraw_list ()

void                planesDraw_list                     (Plane **list,
                                                         int openGLId);

Call OpenGL primitives to draw each plane of the given list. It's a convenient wrapper around planeDraw() for a list.

list :

an array of Plane (NULL terminated).

openGLId :

the OpenGL list to draw to.

planeShowHide_all ()

int                 planeShowHide_all                   (VisuData *visuData,
                                                         Plane **listOfPlanes);

This method test for each node if it is hidden or not by the combination of all the given planes.

visuData :

a VisuData which show or hide nodes to;

listOfPlanes :

an array of Plane, NULL terminated.

Returns :

1 if visu_data_createAllNodes() should be called.

planesGet_visibility ()

gboolean            planesGet_visibility                (Plane **listOfPlanes,
                                                         float point[3]);

Compute the visibility of the given point, following the masking scheme of the given plane list.

listOfPlanes :

an array of Plane, NULL terminated ;

point :

three cartesian coordinates.

Returns :

TRUE if the point is not masked.

planesGet_intersection ()

gboolean            planesGet_intersection              (Plane **listOfPlanes,
                                                         float pointA[3],
                                                         float pointB[3],
                                                         float inter[3],
                                                         gboolean inside);

Compute the location of the intersection point of segment AB with list of planes listOfPlanes. If there are several intersections, the closest to point A is returned. If inside is TRUE, then the intersection point must be within the line [AB].

listOfPlanes :

an array of Plane, NULL terminated ;

pointA :

three cartesian coordinates.

pointB :

three cartesian coordinates.

inter :

a location to store the intersection point.

inside :

a boolean.

Returns :

TRUE if there is an intersection.

planesGet_orderedIntersections ()

gboolean            planesGet_orderedIntersections      (int nPlanes,
                                                         Plane **listOfPlanes,
                                                         float pointA[3],
                                                         float pointB[3],
                                                         float *inter,
                                                         int *index);

Compute the location of the intersection points of segment AB with list of planes listOfPlanes. If there are several intersections, they are ordered by the proximity to point A.

nPlanes :

the number of planes (must be consistent with the number of planes in listOfPlanes!)

listOfPlanes :

an array of Plane, NULL terminated ;

pointA :

three cartesian coordinates.

pointB :

three cartesian coordinates.

inter :

a pointer to the location to store the intersection points. Supposing you know the number of intersection points !

index :

a pointer to the location to store the indices of ordering of the planes.

Returns :

TRUE if the intersections are found.

planeSet_hidingMode ()

int                 planeSet_hidingMode                 (Plane_hidingMode mode);

This method is used to set the hiding mode flag. In union mode, elements are not drwn if they are hidden by one plane at least. In intersection mode, elements are only hidden if masked by all planes. This flag has no relevence if planeShowHide() is used, but only if planeShowHide_all() is called.

mode :

a value related to the hiding mode (look at the enum Plane_hidingMode).

Returns :

1 if planeShowHide_all() should be called.

planesParse_XMLFile ()

gboolean            planesParse_XMLFile                 (gchar *filename,
                                                         Plane ***list,
                                                         GError **error);

Read the given file (syntax in XML) and create a list of planes. This list is an allocated array that should be deallocated with g_free(). This array has always one argument, since it is NULL terminated.

filename :

the file to parse ;

list :

a pointer to store the parsed list (will be allocated and NULL terminated) ;

error :

a pointer to store the error (can be NULL).

Returns :

TRUE if everything goes right, if not and error (if not NULL) is set and contains the message of the error.

planesExport_XMLFile ()

gboolean            planesExport_XMLFile                (gchar *filename,
                                                         Plane **list,
                                                         GError **error);

Export in XML format the given list of planes to the given file.

filename :

the file to export to ;

list :

an array (NULL terminated) to export ;

error :

a pointer to store the error (can be NULL).

Returns :

TRUE if everything goes right, if not and error (if not NULL) is set and contains the message of the error.

Signal Details

The "moved" signal

void                user_function                      (Plane   *plane,
                                                        gpointer user_data)      : Run Last / No Recursion / No Hooks

This signal is emitted each time the plane position is changed (either distance or normal).

plane :

the object emitting the signal.

user_data :

user data set when the signal handler was connected.

Since 3.3