## plane

plane — Adds capabilities to draw and handle planes.

## Synopsis

    enum        Plane_hidingMode;
    #define     PLANE_SIDE_PLUS
    #define     PLANE_SIDE_MINUS
    #define     PLANE_SIDE_NONE

    Plane*      planeNew                        (OpenGLView *view,
                                                 float vect[3],
                                                 float dist,
                                                 Color *color);
    int         planeComputeInter               (Plane *plane,
                                                 OpenGLView *view);
    void        planeDraw                       (Plane *plane,
                                                 OpenGLView *view);
    int         planeShowHide                   (Plane *plane,
                                                 VisuData *visuData,
                                                 gboolean hide,
                                                 float side);
    int         planeShowHide_all               (VisuData *visuData,
                                                 GList *listOfPlanes);
    void        planeGet_nVectUser              (Plane *plane,
                                                 float *vect);
    void        planeGet_color                  (Plane *plane,
                                                 Color **color);
    void        planeGet_distanceFromOrigin     (Plane *plane,
                                                 float *dist);
    GList*      planeGet_intersection           (Plane *plane);
    int         planeGet_hiddenState            (Plane *plane);
    void        planeGet_barycentre             (Plane *plane,
                                                 float *point);
    gboolean    planeGet_rendered               (Plane *plane);
    int         planeSet_color                  (Plane *plane,
                                                 Color *color);
    int         planeSet_normalVector           (Plane *plane,
                                                 float vect[3]);
    int         planeSet_distanceFromOrigin     (Plane *plane,
                                                 float dist);
    int         planeSet_hiddenState            (Plane *plane,
                                                 int side);
    int         planeSet_hidingMode             (Plane_hidingMode mode);
    int         planeSet_rendered               (Plane *plane,
                                                 gboolean rendered);

    int         planesComputeInter_list         (OpenGLView *view,
                                                 GList *list);
    void        planesDraw_list                 (OpenGLView *view,
                                                 GList *list);
    gboolean    planesExport_XMLFile            (gchar *filename,
                                                 GList *list,
                                                 GError **error);
    gboolean    planesParse_XMLFile             (gchar *filename,
                                                 GList **list,
                                                 GError **error);

## Description

Plane are GObjects. They are defined by their normal vector and the distance of the plane with the origin (see `planeSet_normalVector()` and `planeSet_distanceFromOrigin()`). When these informations are given and an OpenGLView 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

### 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                        (OpenGLView *view,
                                                 float vect[3],
                                                 float dist,
                                                 Color *color);

Create a plane with the specified attributes.

`view` : | a OpenGLView object 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 Color.
Returns : | a newly allocated Plane structure.

### planeComputeInter ()

    int         planeComputeInter               (Plane *plane,
                                                 OpenGLView *view);

This method is used to compute the intersections between the bounding box and the plane.

`plane` : | a Plane ;
`view` : | a OpenGLView object that describes the rendering box.
Returns : | 0 if everything went right.

### planeDraw ()

    void        planeDraw                       (Plane *plane,
                                                 OpenGLView *view);

Call OpenGL primitives to draw the plane.

`plane` : | a Plane ;
`view` : | a OpenGLView object that describes the rendering box.

### 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 visuData_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.

### planeShowHide_all ()

    int         planeShowHide_all               (VisuData *visuData,
                                                 GList *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` : | a GList of Plane.
Returns : | 1 if `visuData_createAllNodes()` should be called.

### 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_color ()

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

Stores the color of the plane.

`plane` : | a Plane ;
`color` : | a Color pointer location to store the value.

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

### planeGet_barycentre ()

    void        planeGet_barycentre             (Plane *plane,
                                                 float *point);

Stores the coordinates of barycentre of the plane in `point`. The `planeComputeInter()` should have been called before.

`plane` : | a Plane ;
`point` : | an already alloacted (size 3) float array.

### planeGet_rendered ()

    gboolean    planeGet_rendered               (Plane *plane);

Get the visibility of a plane.

`plane` : | a Plane.
Returns : |

### planeSet_color ()

    int         planeSet_color                  (Plane *plane,
                                                 Color *color);

Change the color of the plane.

`plane` : | a Plane object ;
`color` : | a Color.
Returns : | 0 if everything went right.

### planeSet_normalVector ()

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

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

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

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

### planesComputeInter_list ()

    int         planesComputeInter_list         (OpenGLView *view,
                                                 GList *list);

This method is used to compute the intersections between the bounding box and all the planes of the list. This is a wrapper around `planeComputeInter()`.

`view` : | a OpenGLView object that describes the rendering box ;
`list` : | a GList of Plane.
Returns : | 0 if everything went right.

### planesDraw_list ()

    void        planesDraw_list                 (OpenGLView *view,
                                                 GList *list);

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

`view` : | a OpenGLView object that describes the rendering box ;
`list` : | a GList of Plane.

### planesExport_XMLFile ()

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

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

`filename` : | the file to export to ;
`list` : | the list 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.

### planesParse_XMLFile ()

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

Read the given file (syntax in XML) and create a list of planes.

`filename` : | the file to parse ;
`list` : | a pointer to store the parsed list ;
`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.