GTS Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# 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)
    struct      GtsHSurfaceClass;
    struct      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.

### struct GtsHSurfaceClass

    struct GtsHSurfaceClass;

The hierarchical surface class derived from GtsObjectClass.

### struct GtsHSurface

    struct GtsHSurface {
      GtsObject object;

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

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.

<<< Previous Page | Home | Up | Next Page >>>
Hierarchical vertex split | Graph and operations on graphs