## surfaces

surfaces — Supports loading of .surf files and drawing of surfaces through OpenGL

## Synopsis

    #define     ISOSURFACES_PROPERTY_POTENTIAL
    struct      SurfaceResource_struct;
    typedef     SurfaceResource;
    struct      SurfacesOrder_struct;
    typedef     SurfacesOrder;
    struct      Surfaces_struct;
    typedef     Surfaces;

    Surfaces*   isosurfacesNew                  ();
    void        isosurfacesAllocate             (Surfaces *surf,
                                                 int nsurf,
                                                 int npolys,
                                                 int npoints);
    void        isosurfacesReallocate           (Surfaces **surf,
                                                 int nsurf,
                                                 int npolys,
                                                 int npoints);
    void        isosurfacesFree                 (Surfaces *surf);
    gboolean    isosurfacesRemove               (Surfaces *surf,
                                                 int idSurf);
    gboolean    isosurfacesLoad_file            (const char *file,
                                                 Surfaces **surf,
                                                 GError **error);
    void        isosurfacesDraw_surfaces        (int openGLId,
                                                 OpenGLView *view,
                                                 Surfaces *surf[],
                                                 SurfacesOrder *order);
    void        isosurfacesCopy_resource        (SurfaceResource *res,
                                                 SurfaceResource *res_old);

    void        isoSurfacesSet_fitToBox         (VisuData *data,
                                                 Surfaces *surf);
    void        isosurfacesSet_showAll          (Surfaces *surf,
                                                 gboolean show);
    void        isosurfacesSet_surfaceResource  (Surfaces *surf,
                                                 int surf_index,
                                                 SurfaceResource *res);

    int         isosurfacesGet_nbSurfaces       (Surfaces *surf);
    int         isosurfacesGet_surfaceId        (Surfaces *surf,
                                                 int i);
    int         isosurfacesGet_surfacePosition  (Surfaces *surf,
                                                 int id);
    gboolean    isosurfacesGet_surfaceRendered  (Surfaces *surf,
                                                 int surf_index);
    SurfaceResource* isosurfacesGet_surfaceResource
                                                (Surfaces *surf,
                                                 int surf_index);
    const gchar* isosurfacesGet_surfaceName     (Surfaces *surf,
                                                 int surf_index);
    int*        isosurfacesGet_surfaceSortedById
                                                (Surfaces *surf);
    SurfaceResource* isosurfacesGet_resourceFromName
                                                (const gchar *surf_name,
                                                 gboolean *new);
    int         isosurfacesGet_newId            (Surfaces *surf);

    float*      isosurfacesGet_floatProperty    (Surfaces *surf,
                                                 const gchar *name);
    float*      isosurfacesAdd_floatProperty    (Surfaces *surf,
                                                 const gchar *name);
    gboolean    isosurfacesGet_floatPropertyValue
                                                (Surfaces *surf,
                                                 int idSurf,
                                                 const gchar *name,
                                                 float *value);

    SurfacesOrder* isosurfacesOrder_new         ();
    void        isosurfacesOrder_free           (SurfacesOrder *order);
    void        isosurfacesOrder_polygons       (SurfacesOrder *order,
                                                 Surfaces *surf[]);

    void        isosurfacesInit                 ();
    void        isosurfacesCheck_consistency    (Surfaces *surf);

## Description

Originally written by Luc Billard for his Visualize program. This module allows loading of .surf files to draw scalar fields on top of the current display scene. .surf files are text files which specs are the following :

- 1st line is arbitrary

- 2nd line must contain 3 real (float) values: dxx dyx dyy

- 3rd line must contain 3 real (float) values: dzx dzy dzz

- 4th line must contain 3 positive integers which represents respectively the number of surfaces, the total number of polys, and the total number of points

- Then, for each of these surfaces :

  - next line must contain the name of the surface : it is a string which should match the pattern surface_*

  - next line must contain 2 positive integer values: the number of polys (num_polys) and the number of points (num_points) used by the surface

  - each of the following num_polys lines must match the pattern [n i_1 i_2 i_3 ... i_n] where n is the number of vertices in the poly (n >= 3) and [i_1 i_2 i_3 ... i_n] are the numbering of these vertices (vertices numbered from 1 to num_points)

  - each of the following num_points lines must contain 6 real values for the successive (1 to num_points) points : [x y z nx ny nz], where x y z are the coordinates of the point and nx ny nz are the coordinates of the unit normal at the point

It is the responsibility of the user to guarantee that dxx, dyx, dyy, dzx, dzy, dzz match the one currently loaded in V_Sim's current context. Though if you use panelSurfaces you can ask to resize the surfaces so that they fit in the current loaded box.

## Details

### ISOSURFACES_PROPERTY_POTENTIAL

    #define ISOSURFACES_PROPERTY_POTENTIAL "potential_values"

Flag used in an ASCII surf file to give informations on the value the surface is built from.

### struct SurfaceResource_struct

    struct SurfaceResource_struct {
      /* Name used to label the surface. */
      gchar *surfnom;

      /* Material used to draw a specific surface. */
      Color *color;
      float material[5];

      /* Rendered or not */
      gboolean rendered;
    };

This structure defines some drawing properties of a set of Surfaces.

gchar *`surfnom`; | the name of the surface (in UTF-8) ;
Color *`color`; | a Color for the surface ;
float `material`[5]; | the lighting effects of the surface ;
gboolean `rendered`; | boolean for the visibility of the surface.

### SurfaceResource

    typedef struct SurfaceResource_struct SurfaceResource;

Short name to adress SurfaceResource_struct objects.

### struct SurfacesOrder_struct

    struct SurfacesOrder_struct;

An opaque structure to store the order of drawn polygons when surfaces are involved.

### SurfacesOrder

    typedef struct SurfacesOrder_struct SurfacesOrder;

Short name to adress SurfacesOrder_struct objects.

### struct Surfaces_struct

    struct Surfaces_struct {
      /* Number of different surfaces. */
      int nsurf;

      /* Number of polygons */
      int num_polys, num_points;

      /* Give the number of the surface when the number of the
         polygon is given. */
      int *poly_surf_index;

      /* Return the number of vertices when the id of
         the polygon is given. */
      int *poly_num_vertices;

      /* Return the id j of the vertice of polygon i. */
      int **poly_vertices;

      /* Vectors giving points and normal of the vertice i. */
      float **poly_points;
      float **poly_normals;

      /* The description of the box where surfaces are drawn. */
      float local_box[6];

      /* Resources for each surfaces. */
      SurfaceResource **resources;

      /* Id for each surfaces. */
      int *ids;

      /* Table to add properties to surfaces. */
      GHashTable *properties;
    };

This structure stores surfaces. Several surfaces are stored in a single structure for improved performences.

int `nsurf`; | number of surfaces encoded in this structure ;
int `num_polys`; | number of polygoins stored in this structure ;
int `num_points`; | number of vertices stored in this structure ;
int *`poly_surf_index`; | gives the id of the surface for each polygon ;
int *`poly_num_vertices`; | gives the number of vertices used by each polygons ;
int **`poly_vertices`; | returns the id j of the vertices of polygon i ;
float **`poly_points`; | vectors giving points of the vertex i ;
float **`poly_normals`; | vectors giving normals of the vertex i ;
float `local_box`[6]; | the description of the box where surfaces are drawn ;
SurfaceResource **`resources`; | for each surface points on a SurfaceResource ;
int *`ids`; | gives a list of ids used to index surfaces ;
GHashTable *`properties`; | an hashtable of properties.

### Surfaces

    typedef struct Surfaces_struct Surfaces;

Short name to adress Surfaces_struct objects.

### isosurfacesNew ()

    Surfaces*   isosurfacesNew                  ();

Create a new (with unallocated internal arrays) structure to store surfaces.

Returns : | a newly allocated Surfaces structure.

### isosurfacesAllocate ()

    void        isosurfacesAllocate             (Surfaces *surf,
                                                 int nsurf,
                                                 int npolys,
                                                 int npoints);

Allocate internal arrays to store surfaces having the given description.

`surf` : | a Surfaces structure ;
`nsurf` : | the number of surfaces to store ;
`npolys` : | the number of polygons (in total) ;
`npoints` : | the total number of vertices.

### isosurfacesReallocate ()

    void        isosurfacesReallocate           (Surfaces **surf,
                                                 int nsurf,
                                                 int npolys,
                                                 int npoints);

Change the allocation of internal arrays to store surfaces with the updated description.

`surf` : | a Surfaces structure ;
`nsurf` : | the number of surfaces to store ;
`npolys` : | the number of polygons (in total) ;
`npoints` : | the total number of vertices.

### isosurfacesFree ()

    void        isosurfacesFree                 (Surfaces *surf);

Free all memory associated to the given surfaces.

`surf` : | a Surfaces structure.

### isosurfacesRemove ()

    gboolean    isosurfacesRemove               (Surfaces *surf,
                                                 int idSurf);

Remove from memory all polygons from the given surface.

`surf` : | a Surfaces object ;
`idSurf` : | the id of the surf to remove.
Returns : | TRUE if the surface list is reduced to zero (and `surf` to be freed).

### isosurfacesLoad_file ()

    gboolean    isosurfacesLoad_file            (const char *file,
                                                 Surfaces **surf,
                                                 GError **error);

This loads a surface file and set default material properties for it. See surf file specifications.

`file` : | target file to load ;
`surf` : | a set of surfaces (location) ;
`error` : | a location to store errors.
Returns : | TRUE in case of success, FALSE otherwise. Even in case of success `error` may have been set.

### isosurfacesDraw_surfaces ()

    void        isosurfacesDraw_surfaces        (int openGLId,
                                                 OpenGLView *view,
                                                 Surfaces *surf[],
                                                 SurfacesOrder *order);

Rebuild each visible surface's list. The order in which to draw the surfaces is given in the `order` argument.

`openGLId` : | an id for the OpenGL list ;
`view` : | a OpenGLView object that describes the rendering box.
`surf` : | an array of Surfaces object, must be NULL terminated.
`order` : | a SurfacesOrder object.

### isosurfacesCopy_resource ()

    void        isosurfacesCopy_resource        (SurfaceResource *res,
                                                 SurfaceResource *res_old);

This method copies all values from `res_old` to `res`.

`res` : | an allocated SurfaceResource object to receive values ;
`res_old` : | a SurfaceResource to read the values from.

### isoSurfacesSet_fitToBox ()

    void        isoSurfacesSet_fitToBox         (VisuData *data,
                                                 Surfaces *surf);

This method changes the position of all vertices in the structure to match the box description given in `data`.

`data` : | a VisuData object ;
`surf` : | a set of surfaces.

### isosurfacesSet_showAll ()

    void        isosurfacesSet_showAll          (Surfaces *surf,
                                                 gboolean show);

Shows or hides all surfaces and check their "draw" status in the panel accordingly.

`surf` : | a Surfaces object ;
`show` : | TRUE to show all surfaces, FALSE to hide them.

### isosurfacesSet_surfaceResource ()

    void        isosurfacesSet_surfaceResource  (Surfaces *surf,
                                                 int surf_index,
                                                 SurfaceResource *res);

This method is used to change the resource of a surface.

`surf` : | the surface object ;
`surf_index` : | the number of the surface ;
`res` : | the new resource.

### isosurfacesGet_nbSurfaces ()

    int         isosurfacesGet_nbSurfaces       (Surfaces *surf);

Retrieves th number of surfaces stired in a given `surf` object.

`surf` : | the surface object.
Returns : | number of surfaces.

### isosurfacesGet_surfaceId ()

    int         isosurfacesGet_surfaceId        (Surfaces *surf,
                                                 int i);

This returns for the given `i` its id information.

`surf` : | the surface object ;
`i` : | the number of the surface.
Returns : | the id of the surface or 0, if `i` is invalid.

### isosurfacesGet_surfacePosition ()

    int         isosurfacesGet_surfacePosition  (Surfaces *surf,
                                                 int id);

This returns for the given `id` its number.

`surf` : | the surface object ;
`id` : | the id of the surface.
Returns : | the number of the surface or 0, if `id` is invalid.

### isosurfacesGet_surfaceRendered ()

    gboolean    isosurfacesGet_surfaceRendered  (Surfaces *surf,
                                                 int surf_index);

This returns for the given `surf_index` its visibility.

`surf` : | the surface object ;
`surf_index` : | the number of the surface.
Returns : | the visibility of the surface or FALSE, if `surf_index` is invalid.

### isosurfacesGet_surfaceResource ()

    SurfaceResource* isosurfacesGet_surfaceResource
                                                (Surfaces *surf,
                                                 int surf_index);

This returns for the given `surf_index` its resource information.

`surf` : | the surface object ;
`surf_index` : | the number of the surface.
Returns : | the resource of the surface or NULL, if `surf_index` is invalid.

### isosurfacesGet_surfaceName ()

    const gchar* isosurfacesGet_surfaceName     (Surfaces *surf,
                                                 int surf_index);

This returns for the given `surf_index` its name (1 <= surf_index <= surfaces_number)

`surf` : | the surface object ;
`surf_index` : | the number of the surface.
Returns : | the name of the surface or empty name or NULL, if `surf_index` is invalid.

### isosurfacesGet_surfaceSortedById ()

    int*        isosurfacesGet_surfaceSortedById
                                                (Surfaces *surf);

This returns the surface numbers sorted using their ids.

`surf` : | the surface object.
Returns : | a newly allocated array with surface numbers.

### isosurfacesGet_resourceFromName ()

    SurfaceResource* isosurfacesGet_resourceFromName
                                                (const gchar *surf_name,
                                                 gboolean *new);

This returns the resource information matching the given `surf_name`. If the resource doesn't exist, it is created and `new` is set to TRUE.

`surf_name` : | the name of the surface ;
`new` : | a location to store a boolean value (can be NULL).
Returns : | the resource of the surface or NULL, if `surf_name` is invalid.

### isosurfacesGet_newId ()

    int         isosurfacesGet_newId            (Surfaces *surf);

This returns a unique id to create a new surface.

`surf` : | the surface object.
Returns : | a value suitable to create a new surface in this set of surfaces.

### isosurfacesGet_floatProperty ()

    float*      isosurfacesGet_floatProperty    (Surfaces *surf,
                                                 const gchar *name);

Some properties can be associated to the surfaces stored in `surf`. This method is used to retrieve floating point values properties.

`surf` : | a Surfaces object ;
`name` : | the name of the property to look for.
Returns : | a table with the values if the property is found, NULL otherwise.

### isosurfacesAdd_floatProperty ()

    float*      isosurfacesAdd_floatProperty    (Surfaces *surf,
                                                 const gchar *name);

Some properties can be associated to the surfaces stored in `surf`. This method is add a new property.

`surf` : | a Surfaces object ;
`name` : | the name of the property to add.
Returns : | a newly allocated array that can be populated.

### isosurfacesGet_floatPropertyValue ()

    gboolean    isosurfacesGet_floatPropertyValue
                                                (Surfaces *surf,
                                                 int idSurf,
                                                 const gchar *name,
                                                 float *value);

This method retrieves a float value stored as a property called `name` for the surface defined by its number `idSurf`.

`surf` : | a Surfaces object ;
`idSurf` : | a surface number ;
`name` : | the name of the property to get the value from ;
`value` : | a location to store the value.
Returns : | TRUE if a value is indeed found.

### isosurfacesOrder_new ()

    SurfacesOrder* isosurfacesOrder_new         ();

Create an object to hold the order in which the surfaces must be drawn. See `isosurfacesOrder_polygons()` to set this object.

Returns : | a newly created SurfacesOrder object without any values.

### isosurfacesOrder_free ()

    void        isosurfacesOrder_free           (SurfacesOrder *order);

Free memory used by a SurfacesOrder object.

`order` : | the object to be freed.

### isosurfacesOrder_polygons ()

    void        isosurfacesOrder_polygons       (SurfacesOrder *order,
                                                 Surfaces *surf[]);

Re-orders the polygons in back to front order. This function should be called everytime a redraw is needed.

`order` : | the description of the polygons order ;
`surf` : | an array of Surfaces object, must be NULL terminated.

### isosurfacesInit ()

    void        isosurfacesInit                 ();

Method used to initialised the surface handling, should not be called.

### isosurfacesCheck_consistency ()

    void        isosurfacesCheck_consistency    (Surfaces *surf);

Check if all arrays in the structures are consistent (without overflow).

`surf` : | a Surfaces object.