surfaces

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

Synopsis

#define             VISU_ERROR_ISOSURFACES
#define             VISU_SURFACES_PROPERTY_POTENTIAL
struct              VisuSurfaces;
                    VisuSurfacesClass;
void                visu_surfaces_add                   (VisuSurfaces *surf,
                                                         guint nsurf,
                                                         guint npolys,
                                                         guint npoints);
float *             visu_surfaces_addPropertyFloat      (VisuSurfaces *surf,
                                                         const gchar *name);
void                visu_surfaces_allocate              (VisuSurfaces *surf,
                                                         guint nsurf,
                                                         guint npolys,
                                                         guint npoints);
void                visu_surfaces_checkConsistency      (VisuSurfaces *surf);
GQuark              visu_surfaces_getErrorQuark         (void);
int                 visu_surfaces_getId                 (VisuSurfaces *surf,
                                                         int i);
guint               visu_surfaces_getN                  (VisuSurfaces *surf);
const gchar *       visu_surfaces_getName               (VisuSurfaces *surf,
                                                         int surf_index);
int                 visu_surfaces_getNewId              (VisuSurfaces *surf);
int                 visu_surfaces_getPosition           (VisuSurfaces *surf,
                                                         int id);
float *             visu_surfaces_getPropertyFloat      (VisuSurfaces *surf,
                                                         const gchar *name);
gboolean            visu_surfaces_getPropertyValueFloat (VisuSurfaces *surf,
                                                         int idSurf,
                                                         const gchar *name,
                                                         float *value);
gboolean            visu_surfaces_getRendered           (VisuSurfaces *surf,
                                                         int surf_index);
VisuSurfacesResources * visu_surfaces_getResource       (VisuSurfaces *surf,
                                                         guint i);
VisuSurfacesResources * visu_surfaces_getResourceById   (VisuSurfaces *surf,
                                                         int surf_index);
int *               visu_surfaces_getSortedById         (VisuSurfaces *surf);
gboolean            visu_surfaces_hide                  (VisuSurfaces *surf,
                                                         VisuPlane **planes);
gboolean            visu_surfaces_loadFile              (const char *file,
                                                         VisuSurfaces **surf,
                                                         GError **error);
VisuSurfaces *      visu_surfaces_new                   (guint bufferSize);
gboolean            visu_surfaces_remove                (VisuSurfaces *surf,
                                                         int idSurf);
gboolean            visu_surfaces_setColorAndMaterial   (VisuSurfaces *surf,
                                                         int surf_index,
                                                         ToolColor *color,
                                                         float material[VISU_GL_LIGHT_MATERIAL_N_VALUES]);
gboolean            visu_surfaces_setRendered           (VisuSurfaces *surf,
                                                         int surf_index,
                                                         gboolean status);
void                visu_surfaces_setResource           (VisuSurfaces *surf,
                                                         int surf_index,
                                                         VisuSurfacesResources *res);
void                visu_surfaces_setShowAll            (VisuSurfaces *surf,
                                                         gboolean show);

Object Hierarchy

  GObject
   +----VisuSurfaces

Implemented Interfaces

VisuSurfaces implements VisuBoxed.

Signals

  "added"                                          : No Hooks
  "masked"                                         : No Hooks
  "removed"                                        : No Hooks
  "rendering"                                      : No Hooks

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

VISU_ERROR_ISOSURFACES

#define VISU_ERROR_ISOSURFACES visu_surfaces_getErrorQuark()

Internal function for error handling.


VISU_SURFACES_PROPERTY_POTENTIAL

#define VISU_SURFACES_PROPERTY_POTENTIAL "potential_values"

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


struct VisuSurfaces

struct VisuSurfaces;

All fields are private, use the access routines.


VisuSurfacesClass

typedef struct _VisuSurfacesClass VisuSurfacesClass;

An opaque structure.


visu_surfaces_add ()

void                visu_surfaces_add                   (VisuSurfaces *surf,
                                                         guint nsurf,
                                                         guint npolys,
                                                         guint npoints);

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

surf :

a VisuSurfaces structure ;

nsurf :

the number of surfaces to add ;

npolys :

the number of polygons to add ;

npoints :

the number of vertices to add.

visu_surfaces_addPropertyFloat ()

float *             visu_surfaces_addPropertyFloat      (VisuSurfaces *surf,
                                                         const gchar *name);

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

surf :

a VisuSurfaces object ;

name :

the name of the property to add.

Returns :

a newly allocated array that can be populated.

visu_surfaces_allocate ()

void                visu_surfaces_allocate              (VisuSurfaces *surf,
                                                         guint nsurf,
                                                         guint npolys,
                                                         guint npoints);

Allocate internal arrays to store surfaces having the given description.

surf :

a VisuSurfaces structure ;

nsurf :

the number of surfaces to store ;

npolys :

the number of polygons (in total) ;

npoints :

the total number of vertices.

visu_surfaces_checkConsistency ()

void                visu_surfaces_checkConsistency      (VisuSurfaces *surf);

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

surf :

a VisuSurfaces object.

visu_surfaces_getErrorQuark ()

GQuark              visu_surfaces_getErrorQuark         (void);

Internal routine for error handling.

Returns :

the GQuark associated to errors related to surface files.

visu_surfaces_getId ()

int                 visu_surfaces_getId                 (VisuSurfaces *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.

visu_surfaces_getN ()

guint               visu_surfaces_getN                  (VisuSurfaces *surf);

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

surf :

the surface object.

Returns :

number of surfaces.

visu_surfaces_getName ()

const gchar *       visu_surfaces_getName               (VisuSurfaces *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.

visu_surfaces_getNewId ()

int                 visu_surfaces_getNewId              (VisuSurfaces *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.

visu_surfaces_getPosition ()

int                 visu_surfaces_getPosition           (VisuSurfaces *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.

visu_surfaces_getPropertyFloat ()

float *             visu_surfaces_getPropertyFloat      (VisuSurfaces *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 VisuSurfaces object ;

name :

the name of the property to look for.

Returns :

a table with the values if the property is found, NULL otherwise.

visu_surfaces_getPropertyValueFloat ()

gboolean            visu_surfaces_getPropertyValueFloat (VisuSurfaces *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 VisuSurfaces 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.

visu_surfaces_getRendered ()

gboolean            visu_surfaces_getRendered           (VisuSurfaces *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.

visu_surfaces_getResource ()

VisuSurfacesResources * visu_surfaces_getResource       (VisuSurfaces *surf,
                                                         guint i);

This returns the resource of the ith stored surface. If the surface is known by its id, use visu_surfaces_getResourceById() instead.

surf :

the surface object ;

i :

the ith stored surface.

Returns :

the resource of the surface or NULL, if i is invalid. [transfer none]

Since 3.7


visu_surfaces_getResourceById ()

VisuSurfacesResources * visu_surfaces_getResourceById   (VisuSurfaces *surf,
                                                         int surf_index);

This returns for the given surf_index its resource information.

surf :

the surface object ;

surf_index :

the id of the surface.

Returns :

the resource of the surface or NULL, if surf_index is invalid. [transfer none]

visu_surfaces_getSortedById ()

int *               visu_surfaces_getSortedById         (VisuSurfaces *surf);

This returns the surface numbers sorted using their ids.

surf :

the surface object.

Returns :

a newly allocated array with surface numbers.

visu_surfaces_hide ()

gboolean            visu_surfaces_hide                  (VisuSurfaces *surf,
                                                         VisuPlane **planes);

Change the visibility of polygons stored in surf, following the masking scheme defined by the given list of planes (see VisuPlane).

surf :

a VisuSurfaces object ;

planes :

an array of planes (NULL terminated).

Returns :

TRUE if the surfaces visibility status have been changed.

visu_surfaces_loadFile ()

gboolean            visu_surfaces_loadFile              (const char *file,
                                                         VisuSurfaces **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) ;. [out][transfer full]

error :

a location to store errors.

Returns :

TRUE in case of success, FALSE otherwise. Even in case of success error may have been set. [skip]

visu_surfaces_new ()

VisuSurfaces *      visu_surfaces_new                   (guint bufferSize);

Create a new (with unallocated internal arrays) structure to store surfaces. The buffer size is used to store other values than the position and the normal on each point.

bufferSize :

an integer.

Returns :

a newly allocated VisuSurfaces structure.

visu_surfaces_remove ()

gboolean            visu_surfaces_remove                (VisuSurfaces *surf,
                                                         int idSurf);

Remove from memory all polygons from the given surface.

surf :

a VisuSurfaces object ;

idSurf :

the id of the surf to remove.

Returns :

TRUE if the surface list is reduced to zero (and surf to be freed).

visu_surfaces_setColorAndMaterial ()

gboolean            visu_surfaces_setColorAndMaterial   (VisuSurfaces *surf,
                                                         int surf_index,
                                                         ToolColor *color,
                                                         float material[VISU_GL_LIGHT_MATERIAL_N_VALUES]);

Update the color and material property of given surface.

surf :

the surface object ;

surf_index :

the number of the surface.

color :

a ToolColor object. [transfer none]

material :

the material values. [array fixed-size=5]

Returns :

TRUE if the values are differents.

Since 3.7


visu_surfaces_setRendered ()

gboolean            visu_surfaces_setRendered           (VisuSurfaces *surf,
                                                         int surf_index,
                                                         gboolean status);

Change the visibility status of surface surf_index.

surf :

the surface object ;

surf_index :

the number of the surface.

status :

a boolean.

Returns :

TRUE if the visibility has been indeed changed.

Since 3.7


visu_surfaces_setResource ()

void                visu_surfaces_setResource           (VisuSurfaces *surf,
                                                         int surf_index,
                                                         VisuSurfacesResources *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.

visu_surfaces_setShowAll ()

void                visu_surfaces_setShowAll            (VisuSurfaces *surf,
                                                         gboolean show);

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

surf :

a VisuSurfaces object ;

show :

TRUE to show all surfaces, FALSE to hide them.

Signal Details

The "added" signal

void                user_function                      (VisuSurfaces *surf,
                                                        gpointer      user_data)      : No Hooks

Gets emitted when a new surface is added to the object.

surf :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

Since 3.7


The "masked" signal

void                user_function                      (VisuSurfaces *surf,
                                                        gpointer      user_data)      : No Hooks

Gets emitted when a surface is shown or hidden by a plane.

surf :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

Since 3.7


The "removed" signal

void                user_function                      (VisuSurfaces *surf,
                                                        guint         idSurf,
                                                        gpointer      user_data)      : No Hooks

Gets emitted when a surface is removed from the object.

surf :

the object which received the signal.

idSurf :

the id of the surface that has been removed.

user_data :

user data set when the signal handler was connected.

Since 3.7


The "rendering" signal

void                user_function                      (VisuSurfaces *surf,
                                                        guint         idSurf,
                                                        gpointer      user_data)      : No Hooks

Gets emitted when a rendering property of a surface is modified.

surf :

the object which received the signal.

idSurf :

the id of the surface that has been modified.

user_data :

user data set when the signal handler was connected.

Since 3.7