VisuPlane

VisuPlane — Adds capabilities to draw and handle planes.

Functions

Properties

ToolColor * color Read / Write
gfloat distance Read / Write
gint hidding-side Read / Write
ToolVector * n-vector Read / Write
gfloat opacity Read / Write
gboolean rendered Read / Write

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── ToolDbgObj
        ╰── VisuPlane

Implemented Interfaces

VisuPlane implements VisuBoxed and VisuAnimatable.

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()).

VisuPlane can be used to hide nodes defining their visu_plane_setHiddenState() and visu_plane_set_setHiddingMode(). A list of planes can also be exported or imported from an XML file using visu_plane_set_exportXMLFile() and visu_plane_set_parseXMLFile().

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

Functions

visu_plane_new ()

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

Create a plane with the specified attributes.

Parameters

box

a box description ;.

[transfer full][allow-none]

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_setNormalVector ()

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

Change the normal vector defining the orientation of the plane.

Parameters

plane

a VisuPlane object ;

 

vect

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

[array fixed-size=3]

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_setDistanceFromOrigin ()

gboolean
visu_plane_setDistanceFromOrigin (VisuPlane *plane,
                                  float dist);

Change the position of the plane.

Parameters

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_setOrigin ()

gboolean
visu_plane_setOrigin (VisuPlane *plane,
                      const float origin[3]);

Defines a point belonging to plane instead of defining distance of plane to the box origin.

Parameters

plane

a VisuPlane object.

 

origin

some cartesian coordinates.

[array fixed-size=3]

Returns

TRUE if origin is actually changed.

Since: 3.8


visu_plane_setColor ()

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

Change the color of the plane.

Parameters

plane

a VisuPlane object ;

 

color

a ToolColor.

 

Returns

TRUE if color changed.


visu_plane_getBasis ()

void
visu_plane_getBasis (const 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.

Parameters

plane

a VisuPlane ;

 

xyz

two vectors.

 

center

a point in cartesian coordinates.

 

visu_plane_getIntersection ()

GList *
visu_plane_getIntersection (const VisuPlane *plane);

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

Parameters

plane

a VisuPlane.

 

Returns

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

[transfer none][element-type ToolVector]


visu_plane_getReducedIntersection ()

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

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

Parameters

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_getNVectUser ()

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

Parameters

plane

a VisuPlane.

 

vect

an already alloacted (size 3) float array.

 

visu_plane_getNVect ()

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

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

Parameters

plane

a VisuPlane.

 

vect

an already alloacted (size 3) float array.

 

visu_plane_getDistanceFromOrigin ()

gfloat
visu_plane_getDistanceFromOrigin (const VisuPlane *plane);

Stores the distance of the plane to the origin.

Parameters

plane

a VisuPlane ;

 

Returns

a float value.


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.

Parameters

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_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 .

Parameters

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_getColor ()

const ToolColor *
visu_plane_getColor (VisuPlane *plane);

Stores the color of the plane.

Parameters

plane

a VisuPlane ;

 

Returns

a ToolColor.

[transfer none]


visu_plane_setHiddenState ()

gboolean
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.

Parameters

Returns

TRUE if the hidding side was actually changed.


visu_plane_getHiddenState ()

int
visu_plane_getHiddenState (const VisuPlane *plane);

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

Parameters

plane

a VisuPlane.

 

Returns

the state, defined by VISU_PLANE_SIDE_PLUS or VISU_PLANE_SIDE_MINUS or VISU_PLANE_SIDE_NONE.


visu_plane_setRendered ()

gboolean
visu_plane_setRendered (VisuPlane *plane,
                        gboolean rendered);

Change the visibility of the plane.

Parameters

plane

a VisuPlane ;

 

rendered

TRUE to make the plane drawable.

 

Returns

TRUE if the visibility is actually changed.


visu_plane_getRendered ()

gboolean
visu_plane_getRendered (const VisuPlane *plane);

Get the visibility of a plane.

Parameters

plane

a VisuPlane.

 

Returns

TRUE if the plane is visible.


visu_plane_getVisibility ()

gboolean
visu_plane_getVisibility (const VisuPlane *plane,
                          float point[3]);

Test the visibility of a given point with respect to the plane attributes.

Parameters

plane

a VisuPlane object.

 

point

some coordinates.

[array fixed-size=3]

Returns

TRUE if the given point is not masked by the plane .

Since: 3.8


visu_plane_getOpacity ()

gfloat
visu_plane_getOpacity (const VisuPlane *plane);

Retrieves the plane opacity.

Parameters

plane

a VisuPlane object.

 

Returns

a float within [0;1].

Since: 3.8


visu_plane_setOpacity ()

gboolean
visu_plane_setOpacity (VisuPlane *plane,
                       gfloat opacity);

Defines the plane opacity. Planes can be coloured with alpha channel colours. The opacity is an additional parameter that can be used to animate plane apparition for instance.

Parameters

plane

a VisuPlane object.

 

opacity

a float in [0;1].

 

Returns

TRUE if value is actually changed.

Since: 3.8


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.

Parameters

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.

Types and Values

struct VisuPlaneClass

struct VisuPlaneClass {
  VisuObjectClass parent;
};

An opaque structure.

Members

VisuObjectClass parent;

the parent.

 

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.


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.


VisuPlane

typedef struct _VisuPlane VisuPlane;

All fields are private, use the access routines.

Property Details

The “color” property

  “color”                    ToolColor *

rendering color.

Flags: Read / Write


The “distance” property

  “distance”                 gfloat

distance to origin.

Flags: Read / Write

Default value: 0


The “hidding-side” property

  “hidding-side”             gint

hidding property.

Flags: Read / Write

Allowed values: [-1,1]

Default value: 0


The “n-vector” property

  “n-vector”                 ToolVector *

normal vector.

Flags: Read / Write


The “opacity” property

  “opacity”                  gfloat

opacity property.

Flags: Read / Write

Allowed values: [0,1]

Default value: 1


The “rendered” property

  “rendered”                 gboolean

rendering property.

Flags: Read / Write

Default value: TRUE

Signal Details

The “moved” signal

void
user_function (VisuPlane *plane,
               gpointer   user_data)

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

Parameters

plane

the object emitting the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 3.3


The “rendering” signal

void
user_function (VisuPlane *plane,
               gpointer   user_data)

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

Parameters

plane

the object emitting the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 3.7