Hierarchical surfaces

Name

Hierarchical surfaces -- extension of progressive surfaces allowing arbitrary sequences of vertex split or collapse.

Synopsis


#include <gts.h>


#define     GTS_HSURFACE_CLASS              (klass)
#define     GTS_HSURFACE                    (obj)
#define     GTS_IS_HSURFACE                 (obj)
            GtsHSurfaceClass;
            GtsHSurface;

GtsHSurfaceClass* gts_hsurface_class        (void);
GtsHSurface* gts_hsurface_new               (GtsHSurfaceClass *klass,
                                             GtsHSplitClass *hsplit_class,
                                             GtsPSurface *psurface,
                                             GtsKeyFunc expand_key,
                                             gpointer expand_data,
                                             GtsKeyFunc collapse_key,
                                             gpointer collapse_data);
void        gts_hsurface_traverse           (GtsHSurface *hsurface,
                                             GTraverseType order,
                                             gint depth,
                                             GtsSplitTraverseFunc func,
                                             gpointer data);
guint       gts_hsurface_height             (GtsHSurface *hsurface);
void        gts_hsurface_foreach            (GtsHSurface *hsurface,
                                             GTraverseType order,
                                             GtsFunc func,
                                             gpointer data);

Description

Hierarchical surfaces are used to manage sequences of vertex splits or collapses which can be different from the initial sequence described by the progressive surface. In this way different branches of the vertex split tree can be collapsed or expanded resulting in a level of detail varying across different parts of the surface. This is the fundamental mechanism of view-dependent level of detail.

Hierarchical surfaces maintain two priority heaps one containing the next vertices (GtsHSplit) ready to be expanded, the other the next vertices ready to be collapsed. By updating the priorities for these vertices as the view point changes and collapsing or expanding the top ones until a given criterium is verified, the level of detail can be dynamically adapted.

Details

GTS_HSURFACE_CLASS()

#define     GTS_HSURFACE_CLASS(klass)

Casts klass to GtsHSurfaceClass.

klass :

a descendant of GtsHSurfaceClass.


GTS_HSURFACE()

#define     GTS_HSURFACE(obj)

Casts obj to GtsHSurface.

obj :

a descendant of GtsHSurface.


GTS_IS_HSURFACE()

#define     GTS_IS_HSURFACE(obj)

Evaluates to TRUE if obj is a GtsHSurface.

obj :

a pointer to test.


GtsHSurfaceClass

typedef struct {
  GtsObjectClass parent_class;
} GtsHSurfaceClass;

The hierarchical surface class derived from GtsObjectClass.


GtsHSurface

typedef struct {
  GtsObject object;

  GtsSurface * s;
  GSList * roots;
  GtsEHeap * expandable;
  GtsEHeap * collapsable;
  GPtrArray * split;
  guint nvertex;
} GtsHSurface;

The hierarchical surface object.

GtsObject object;

The parent object.

GtsSurface *s;

The GtsSurface being refined or coarsened.

GSList *roots;

Private field.

GtsEHeap *expandable;

GtsEHeap of the expandable GtsHSplit sorted by priority.

GtsEHeap *collapsable;

GtsEHeap of the collapsable GtsHSplit sorted by priority.

GPtrArray *split;

Private field.

guint nvertex;

Private field.


gts_hsurface_class ()

GtsHSurfaceClass* gts_hsurface_class        (void);

Returns :

the GtsHSurfaceClass.


gts_hsurface_new ()

GtsHSurface* gts_hsurface_new               (GtsHSurfaceClass *klass,
                                             GtsHSplitClass *hsplit_class,
                                             GtsPSurface *psurface,
                                             GtsKeyFunc expand_key,
                                             gpointer expand_data,
                                             GtsKeyFunc collapse_key,
                                             gpointer collapse_data);

klass :

a GtsHSurfaceClass.

hsplit_class :

a GtsHSplitClass.

psurface :

a GtsPSurface.

expand_key :

a GtsKeyFunc used to order the priority heap of expandable GtsHSplit.

expand_data :

data to be passed to expand_key.

collapse_key :

a GtsKeyFunc used to order the priority heap of collapsable GtsHSplit.

collapse_data :

data to be passed to collapsed_key.

Returns :

a new GtsHSurface, hierarchical extension of psurface and using GtsHSplit of class hsplit_class. Note that psurface is destroyed in the process.


gts_hsurface_traverse ()

void        gts_hsurface_traverse           (GtsHSurface *hsurface,
                                             GTraverseType order,
                                             gint depth,
                                             GtsSplitTraverseFunc func,
                                             gpointer data);

Traverses a hierarchical surface starting from its roots. It calls the given function for each GtsHSplit visited. See also gts_split_traverse().

hsurface :

a GtsHSurface.

order :

the order in which nodes are visited - G_PRE_ORDER or G_POST_ORDER.

depth :

the maximum depth of the traversal. Nodes below this depth will not be visited. If max_depth is -1 all nodes in the tree are visited. If depth is 1, only the root is visited. If depth is 2, the root and its children are visited. And so on.

func :

the function to call for each visited GtsHSplit.

data :

user data to pass to the function.


gts_hsurface_height ()

guint       gts_hsurface_height             (GtsHSurface *hsurface);

hsurface :

a GtsHSurface.

Returns :

the maximum height of the tree described by hsurface.


gts_hsurface_foreach ()

void        gts_hsurface_foreach            (GtsHSurface *hsurface,
                                             GTraverseType order,
                                             GtsFunc func,
                                             gpointer data);

Starts by expanding all the GtsHSplit of hsurface. If order is G_PRE_ORDER, calls func for each GtsHSplit and collapses it. If order is G_POST_ORDER, collapses each GtsHSplit first and then calls func. The traversal can be halted at any point by returning TRUE from func.

hsurface :

a GtsHSurface.

order :

the order in which GtsHSplit are visited - G_PRE_ORDER or G_POST_ORDER.

func :

the function to call for each visited GtsHSplit.

data :

user data to pass to the function.