plane

plane — Adds capabilities to draw and handle planes.

Synopsis

#define             VISU_PLANE_SIDE_MINUS
#define             VISU_PLANE_SIDE_NONE
#define             VISU_PLANE_SIDE_PLUS
                    VisuPlane;
                    VisuPlaneClass;
enum                VisuPlaneHidingMode;
gboolean            visu_plane_class_exportXMLFile      (const gchar *filename,
                                                         VisuPlane **list,
                                                         GError **error);
gboolean            visu_plane_class_getIntersection    (VisuPlane **listOfVisuPlanes,
                                                         float pointA[3],
                                                         float pointB[3],
                                                         float inter[3],
                                                         gboolean inside);
gboolean            visu_plane_class_getOrderedIntersections
                                                        (int nVisuPlanes,
                                                         VisuPlane **listOfVisuPlanes,
                                                         float pointA[3],
                                                         float pointB[3],
                                                         float *inter,
                                                         int *index);
gboolean            visu_plane_class_getVisibility      (VisuPlane **listOfVisuPlanes,
                                                         float point[3]);
gboolean            visu_plane_class_parseXMLFile       (gchar *filename,
                                                         VisuPlane ***planes,
                                                         GError **error);
int                 visu_plane_class_setHiddingMode     (VisuPlaneHidingMode mode);
gboolean            visu_plane_class_showHideAll        (VisuPlane **listOfVisuPlanes,
                                                         VisuData *visuData);
void                visu_plane_getBasis                 (VisuPlane *plane,
                                                         float xyz[2][3],
                                                         float center[3]);
ToolColor *         visu_plane_getColor                 (VisuPlane *plane);
gfloat              visu_plane_getDistanceFromOrigin    (VisuPlane *plane);
int                 visu_plane_getHiddenState           (VisuPlane *plane);
GList *             visu_plane_getIntersection          (VisuPlane *plane);
gboolean            visu_plane_getLineIntersection      (const VisuPlane *plane,
                                                         const float A[3],
                                                         const float B[3],
                                                         float *lambda);
void                visu_plane_getNVect                 (VisuPlane *plane,
                                                         float *vect);
void                visu_plane_getNVectUser             (VisuPlane *plane,
                                                         float *vect);
gboolean            visu_plane_getPlaneIntersection     (const VisuPlane *plane1,
                                                         const VisuPlane *plane2,
                                                         float A[3],
                                                         float B[3]);
float *             visu_plane_getReducedIntersection   (VisuPlane *plane,
                                                         guint *nVals);
gboolean            visu_plane_getRendered              (VisuPlane *plane);
VisuPlane *         visu_plane_new                      (VisuBox *box,
                                                         float vect[3],
                                                         float dist,
                                                         ToolColor *color);
VisuPlane *         visu_plane_newUndefined             (void);
gboolean            visu_plane_setColor                 (VisuPlane *plane,
                                                         ToolColor *color);
gboolean            visu_plane_setDistanceFromOrigin    (VisuPlane *plane,
                                                         float dist);
int                 visu_plane_setHiddenState           (VisuPlane *plane,
                                                         int side);
gboolean            visu_plane_setNormalVector          (VisuPlane *plane,
                                                         float vect[3]);
gboolean            visu_plane_setRendered              (VisuPlane *plane,
                                                         gboolean rendered);

Object Hierarchy

  GObject
   +----VisuPlane

Implemented Interfaces

VisuPlane implements VisuBoxed.

Signals

  "moved"                                          : No Hooks
  "rendering"                                      : No Hooks

Description

A VisuPlane is a GObject. It is defined by its normal vector and the distance of the plane with the origin (see visu_plane_setNormalVector() and visu_plane_setDistanceFromOrigin()). When these informations are given and an VisuGlView is used to render the plane, V_Sim computes the intersections of the plane with the bounding box (see visu_plane_getIntersection()).

VisuPlanes can be used to hide nodes defining their visu_plane_setHiddenState() and visu_plane_class_setHiddingMode(). A list of planes can also be exported or imported from an XML file using visu_plane_class_exportXMLFile() and visu_plane_class_parseXMLFile().

VisuPlanes 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

VISU_PLANE_SIDE_MINUS

#define VISU_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.


VISU_PLANE_SIDE_NONE

#define VISU_PLANE_SIDE_NONE 0

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


VISU_PLANE_SIDE_PLUS

#define VISU_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.


VisuPlane

typedef struct _VisuPlane VisuPlane;

All fields are private, use the access routines.


VisuPlaneClass

typedef struct _VisuPlaneClass VisuPlaneClass;

An opaque structure.


enum VisuPlaneHidingMode

typedef enum {
    VISU_PLANE_HIDE_UNION,
    VISU_PLANE_HIDE_INTER,
    VISU_PLANE_HIDE_N_VALUES
} VisuPlaneHidingMode;

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

VISU_PLANE_HIDE_UNION

element are masked if one plane at least mask it ;

VISU_PLANE_HIDE_INTER

element are masked if all planes mask it ;

VISU_PLANE_HIDE_N_VALUES

number of masking possibilities.

visu_plane_class_exportXMLFile ()

gboolean            visu_plane_class_exportXMLFile      (const gchar *filename,
                                                         VisuPlane **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.

visu_plane_class_getIntersection ()

gboolean            visu_plane_class_getIntersection    (VisuPlane **listOfVisuPlanes,
                                                         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 listOfVisuPlanes. 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].

listOfVisuPlanes :

an array of VisuPlane, 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.

visu_plane_class_getOrderedIntersections ()

gboolean            visu_plane_class_getOrderedIntersections
                                                        (int nVisuPlanes,
                                                         VisuPlane **listOfVisuPlanes,
                                                         float pointA[3],
                                                         float pointB[3],
                                                         float *inter,
                                                         int *index);

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

nVisuPlanes :

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

listOfVisuPlanes :

an array of VisuPlane, 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.

visu_plane_class_getVisibility ()

gboolean            visu_plane_class_getVisibility      (VisuPlane **listOfVisuPlanes,
                                                         float point[3]);

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

listOfVisuPlanes :

an array of VisuPlane, NULL terminated ;

point :

three cartesian coordinates.

Returns :

TRUE if the point is not masked.

visu_plane_class_parseXMLFile ()

gboolean            visu_plane_class_parseXMLFile       (gchar *filename,
                                                         VisuPlane ***planes,
                                                         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 ;. [type filename]

planes :

a pointer to store the parsed list (will be allocated and NULL terminated) ;. [out callee-allocates][array zero-terminated=1]

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. [skip]

visu_plane_class_setHiddingMode ()

int                 visu_plane_class_setHiddingMode     (VisuPlaneHidingMode 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.

mode :

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

Returns :

1 if visu_plane_class_showHideAll() should be called.

visu_plane_class_showHideAll ()

gboolean            visu_plane_class_showHideAll        (VisuPlane **listOfVisuPlanes,
                                                         VisuData *visuData);

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

listOfVisuPlanes :

(array zero-terminated=1) (element-type VisuPlane*) (transfer none): an array of VisuPlane, NULL terminated.

visuData :

a VisuData which show or hide nodes to;

Returns :

TRUE if VisuNodeArray::VisibilityChanged signal should be called.

visu_plane_getBasis ()

void                visu_plane_getBasis                 (VisuPlane *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 VisuPlane ;

xyz :

two vectors.

center :

a point in cartesian coordinates.

visu_plane_getColor ()

ToolColor *         visu_plane_getColor                 (VisuPlane *plane);

Stores the color of the plane.

plane :

a VisuPlane ;

Returns :

a ToolColor. [transfer none]

visu_plane_getDistanceFromOrigin ()

gfloat              visu_plane_getDistanceFromOrigin    (VisuPlane *plane);

Stores the distance of the plane to the origin.

plane :

a VisuPlane ;

Returns :

a float value.

visu_plane_getHiddenState ()

int                 visu_plane_getHiddenState           (VisuPlane *plane);

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

plane :

a VisuPlane.

Returns :

the state, defined by VISU_PLANE_SIDE_PLUS or VISU_PLANE_SIDE_MINUS or VISU_PLANE_SIDE_NONE.

visu_plane_getIntersection ()

GList *             visu_plane_getIntersection          (VisuPlane *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 VisuPlane.

Returns :

a list of float[3] elements. This list is owned by V_Sim. [transfer none][element-type ToolVector]

visu_plane_getLineIntersection ()

gboolean            visu_plane_getLineIntersection      (const VisuPlane *plane,
                                                         const float A[3],
                                                         const float B[3],
                                                         float *lambda);

If there is an intersection M between line (AB) and plane, then this function calculates M coordinates as M = A + lambda * AB.

plane :

a VisuPlane object.

A :

coordinates of point A. [array fixed-size=3]

B :

coordinates of point B. [array fixed-size=3]

lambda :

a location to store the intersecting factor. [out caller-allocates][allow-none]

Returns :

TRUE if there is an intersection between line (AB) and the plane.

Since 3.6


visu_plane_getNVect ()

void                visu_plane_getNVect                 (VisuPlane *plane,
                                                         float *vect);

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

plane :

a VisuPlane.

vect :

an already alloacted (size 3) float array.

visu_plane_getNVectUser ()

void                visu_plane_getNVectUser             (VisuPlane *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 VisuPlane.

vect :

an already alloacted (size 3) float array.

visu_plane_getPlaneIntersection ()

gboolean            visu_plane_getPlaneIntersection     (const VisuPlane *plane1,
                                                         const VisuPlane *plane2,
                                                         float A[3],
                                                         float B[3]);

Calculates the intersection between plane1 and plane2, if it exists. The intersection is returned in A and B as the coordinates of the two points on the border of plane1 that intersect plane2.

plane1 :

a VisuPlane object.

plane2 :

another VisuPlane object.

A :

the coordinates of the first point of intersection. [out][array fixed-size=3]

B :

the coordinates of the second point of intersection. [out][array fixed-size=3]

Returns :

TRUE if there is an intersection between plane1 and plane2.

Since 3.7


visu_plane_getReducedIntersection ()

float *             visu_plane_getReducedIntersection   (VisuPlane *plane,
                                                         guint *nVals);

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

plane :

a VisuPlane object.

nVals :

a location for an integer.

Returns :

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

Since 3.6


visu_plane_getRendered ()

gboolean            visu_plane_getRendered              (VisuPlane *plane);

Get the visibility of a plane.

plane :

a VisuPlane.

Returns :

TRUE if the plane is visible.

visu_plane_new ()

VisuPlane *         visu_plane_new                      (VisuBox *box,
                                                         float vect[3],
                                                         float dist,
                                                         ToolColor *color);

Create a plane with the specified attributes.

box :

a box description ;. [transfer full]

vect :

three values defining the normal vector (unitary or not) ;. [array fixed-size=3]

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

visu_plane_newUndefined ()

VisuPlane *         visu_plane_newUndefined             (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 VisuPlane structure. [transfer full]

visu_plane_setColor ()

gboolean            visu_plane_setColor                 (VisuPlane *plane,
                                                         ToolColor *color);

Change the color of the plane.

plane :

a VisuPlane object ;

color :

a ToolColor.

Returns :

0 if everything went right.

visu_plane_setDistanceFromOrigin ()

gboolean            visu_plane_setDistanceFromOrigin    (VisuPlane *plane,
                                                         float dist);

Change the position of the plane.

plane :

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

visu_plane_setHiddenState ()

int                 visu_plane_setHiddenState           (VisuPlane *plane,
                                                         int side);

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

plane :

a VisuPlane ;

side :

a key, VISU_PLANE_SIDE_NONE, VISU_PLANE_SIDE_PLUS or VISU_PLANE_SIDE_MINUS.

Returns :

1 if visu_plane_class_showHideAll() should be called.

visu_plane_setNormalVector ()

gboolean            visu_plane_setNormalVector          (VisuPlane *plane,
                                                         float vect[3]);

Change the normal vector defining the orientation of the plane.

plane :

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

visu_plane_setRendered ()

gboolean            visu_plane_setRendered              (VisuPlane *plane,
                                                         gboolean rendered);

Change the visibility of the plane.

plane :

a VisuPlane ;

rendered :

TRUE to make the plane drawable.

Returns :

TRUE if visu_plane_class_showHideAll() should be called.

Signal Details

The "moved" signal

void                user_function                      (VisuPlane *plane,
                                                        gpointer   user_data)      : 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


The "rendering" signal

void                user_function                      (VisuPlane *plane,
                                                        gpointer   user_data)      : No Hooks

This signal is emitted each time the rendering properties (color, visibility...) are affected.

plane :

the object emitting the signal.

user_data :

user data set when the signal handler was connected.

Since 3.7