BRL-CAD
Loading...
Searching...
No Matches
lod.h
Go to the documentation of this file.
1/* L O D . H
2 * BRL-CAD
3 *
4 * Copyright (c) 2004-2025 United States Government as represented by
5 * the U.S. Army Research Laboratory.
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public License
9 * version 2.1 as published by the Free Software Foundation.
10 *
11 * This library is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this file; see the file named COPYING for more
18 * information.
19 */
20
21/*----------------------------------------------------------------------*/
22/** @addtogroup bv_lod
23 *
24 * @brief
25 * Functions for generating view dependent level-of-detail data,
26 * particularly for meshes.
27 */
28/** @{ */
29/* @file lod.h */
30
31#ifndef BV_LOD_H
32#define BV_LOD_H
33
34#include "common.h"
35#include "vmath.h"
36#include "bu/ptbl.h"
37#include "bv/defines.h"
38
40
41/* Given a view, construct either an oriented bounding box or a view frustum
42 * extruded to contain scene objects visible in the view. Conceptually, think
43 * of it as a framebuffer pane pushed through the scene in the direction the
44 * camera is looking. If the view width and height are not set or there is
45 * some other problem, no volume is computed. This function is intended
46 * primarily to be set as an updating callback for the bview structure. */
47BV_EXPORT extern void
49
50/* Given a screen x,y coordinate, construct the set of all scene objects whose
51 * AABB intersect with the OBB created by the projection of that pixel through
52 * the scene. sset holds the struct bv_scene_obj pointers of the selected
53 * objects. */
54BV_EXPORT int
55bv_view_objs_select(struct bu_ptbl *sset, struct bview *v, int x, int y);
56
57/* Given a screen x1,y1,x2,y2 rectangle, construct and return the set of all scene
58 * objects whose AABB intersect with the OBB created by the projection of that
59 * rectangle through the scene. */
60BV_EXPORT int
61bv_view_objs_rect_select(struct bu_ptbl *sset, struct bview *v, int x1, int y1, int x2, int y2);
62
63/* Storing and reading from a lot of small, individual files doesn't work very
64 * well on some platforms. We provide a "context" to manage bookkeeping of data
65 * across objects. The details are implementation internal - the application
66 * will simply create a context with a file name and provide it to the various
67 * LoD calls. */
72
73/* Create an LoD context using "name". If data is already present associated
74 * with that name it will be loaded, otherwise a new storage structure will be
75 * initialized. If creation or loading fails for any reason the return value
76 * NULL.
77 *
78 * Note that "name" should be a full, unique path associated with the source
79 * database. libbu will manage where the context data is cached.
80*/
83
84/* Free all memory associated with context c. Note that this call does NOT
85 * remove the on-disk data. */
86BV_EXPORT void
88
89/* Remove cache data associated with key. If key == 0, remove ALL cache data
90 * associated with all LoD objects in c. (i.e. a full LoD cache reset for that
91 * .g database). If key == 0 AND c == NULL, clear all LoD cache data for all
92 * .g databases associated with the current user's cache.
93 */
94BV_EXPORT void
95bv_mesh_lod_clear_cache(struct bv_mesh_lod_context *c, unsigned long long key);
96
97/**
98 * Given a set of points and faces, calculate a lookup key and determine if the
99 * cache has the LoD data for this particular mesh. If it does not, do the
100 * initial calculations to generate the cached LoD data needed for subsequent
101 * lookups, otherwise just return the calculated key.
102 *
103 * This is potentially an expensive operation, particularly if the LoD data set
104 * must be generated for the mesh.
105 *
106 * If user_key != 0, it will be used instead of the mesh data hash as the db
107 * key to be used for subsequent lookups. Typically calculated with
108 * bu_data_hash from user supplied data, if the mesh data is not
109 * the desired source of the key.
110 *
111 * Note: to clear pre-existing cached data, run bv_mesh_lod_clear_cache();
112 *
113 * @return the lookup key calculated from the data */
114BV_EXPORT unsigned long long
115bv_mesh_lod_cache(struct bv_mesh_lod_context *c, const point_t *v, size_t vcnt, const vect_t *vn, int *f, size_t fcnt, unsigned long long user_key, fastf_t fratio);
116
117
118/**
119 * Given a name, see if the context has a key associated with that name.
120 * If so return it, else return zero.
121 *
122 * Users of this feature need to be aware that it is the responsibility
123 * of the application to maintain the LoD cache data and keep it current -
124 * it is quite possible, in a data sense, for the LoD data to be out of
125 * date if something has changed the named geometry object and not updated
126 * the cache.
127 *
128 * The advantage of this feature, if the application does maintain the
129 * data correctly, is to make it possible to load a high level view of
130 * a large model without having to hash the full mesh data of the model
131 * to retrieve the data.
132 */
133BV_EXPORT unsigned long long
134bv_mesh_lod_key_get(struct bv_mesh_lod_context *c, const char *name);
135
136/**
137 * Given a name and a key, instruct the context to associate that name with
138 * the key.
139 *
140 * Returns 0 if successful, else error
141 */
142BV_EXPORT int
143bv_mesh_lod_key_put(struct bv_mesh_lod_context *c, const char *name, unsigned long long key);
144
145/**
146 * Set up the bv_mesh_lod container using cached LoD information associated
147 * with key. If no cached data has been prepared, a NULL container is
148 * returned - to prepare cached data, call bv_mesh_lod_cache with the original
149 * mesh input data. This call is intended to be usable in situations where
150 * we don't want to pull the full mesh data set into memory, so we can't assume
151 * the original data is present.
152 *
153 * Note: bv_mesh_lod assumes a non-changing mesh - if the mesh is changed after
154 * it is created, the internal container does *NOT* automatically update. In
155 * that case the old struct should be destroyed and a new one created.
156 *
157 * A bv_mesh_lod return from this function will be initialized only to the
158 * lowest level of data (i.e. the coarsest possible representation of the
159 * object.) To tailor the data, use the bv_mesh_lod_view function. For lower
160 * level control, the bv_mesh_lod_level function may be used to explicitly
161 * manipulate the loaded LoD (usually used for debugging, but also useful if an
162 * application wishes to visualize levels explicitly.)
163 */
164BV_EXPORT struct bv_mesh_lod *
165bv_mesh_lod_create(struct bv_mesh_lod_context *c, unsigned long long key);
166
167/* Clean up the lod container. */
168BV_EXPORT void
170
171/**
172 * Given a scene object with mesh LoD data stored in s->draw_data, reduce
173 * memory footprint (for use after client codes have completed use of a
174 * particular level's info, but aren't done with the object. Main use case
175 * currently is OpenGL display lists - once generated, we can clear the
176 * internally stored LoD data until the level changes. Note that there is a
177 * re-loading performance penalty as a trade-off to the memory savings. */
178BV_EXPORT void
180
181/**
182 * Given a scene object with mesh LoD data stored in s->draw_data and a bview,
183 * load the appropriate level of detail for displaying the mesh in that view.
184 * Set reset == 1 if the caller wants to undo a memshrink operation even if the
185 * level isn't changed by the current view settings.
186 *
187 * Returns the level selected. If v == NULL, return current level of l. If
188 * there is an error or l == NULL, return -1; */
189BV_EXPORT int
190bv_mesh_lod_view(struct bv_scene_obj *s, struct bview *v, int reset);
191
192/**
193 * Given a scene object with mesh LoD data stored in s->draw_data and a detail
194 * level, load the appropriate data. This is not normally used by client codes
195 * directly, but may be needed if an app needs manipulate the level of detail
196 * without a view. Set reset == 1 if the caller wants to undo a memshrink
197 * operation even if the level isn't changed by the current view settings.
198 *
199 * Returns the level selected. If level == -1, return current level of l. If
200 * there is an error, return -1; */
201BV_EXPORT int
203
204/* Free a scene object's LoD data. Suitable as a s_free_callback function
205 * for a bv_scene_obj. This function will also trigger any additional
206 * "free" callback functions which might be defined for the LoD container. */
207BV_EXPORT void
209
210
211
212/* In order to preserve library barriers, a number of operations needed to
213 * realize LoD drawing are defined at other library layers and made available
214 * to the core LoD management logic with callbacks */
215
216/* Set function callbacks for retrieving and freeing high levels of mesh detail */
217BV_EXPORT void
218bv_mesh_lod_detail_setup_clbk(struct bv_mesh_lod *lod, int (*clbk)(struct bv_mesh_lod *, void *), void *cb_data);
219BV_EXPORT void
221BV_EXPORT void
223
225
226#endif /* BV_LOD_H */
227/** @} */
228/*
229 * Local Variables:
230 * mode: C
231 * tab-width: 8
232 * indent-tabs-mode: t
233 * c-file-style: "stroustrup"
234 * End:
235 * ex: shiftwidth=4 tabstop=8
236 */
Definition dvec.h:74
Header file for the BRL-CAD common definitions.
int bv_mesh_lod_key_put(struct bv_mesh_lod_context *c, const char *name, unsigned long long key)
void bv_mesh_lod_context_destroy(struct bv_mesh_lod_context *c)
int bv_view_objs_rect_select(struct bu_ptbl *sset, struct bview *v, int x1, int y1, int x2, int y2)
void bv_view_bounds(struct bview *v)
int bv_mesh_lod_view(struct bv_scene_obj *s, struct bview *v, int reset)
int bv_mesh_lod_level(struct bv_scene_obj *s, int level, int reset)
int bv_view_objs_select(struct bu_ptbl *sset, struct bview *v, int x, int y)
void bv_mesh_lod_detail_setup_clbk(struct bv_mesh_lod *lod, int(*clbk)(struct bv_mesh_lod *, void *), void *cb_data)
void bv_mesh_lod_clear_cache(struct bv_mesh_lod_context *c, unsigned long long key)
struct bv_mesh_lod * bv_mesh_lod_create(struct bv_mesh_lod_context *c, unsigned long long key)
void bv_mesh_lod_memshrink(struct bv_scene_obj *s)
unsigned long long bv_mesh_lod_key_get(struct bv_mesh_lod_context *c, const char *name)
void bv_mesh_lod_detail_free_clbk(struct bv_mesh_lod *lod, int(*clbk)(struct bv_mesh_lod *, void *))
void bv_mesh_lod_free(struct bv_scene_obj *s)
void bv_mesh_lod_destroy(struct bv_mesh_lod *l)
struct bv_mesh_lod_context * bv_mesh_lod_context_create(const char *name)
unsigned long long bv_mesh_lod_cache(struct bv_mesh_lod_context *c, const point_t *v, size_t vcnt, const vect_t *vn, int *f, size_t fcnt, unsigned long long user_key, fastf_t fratio)
void bv_mesh_lod_detail_clear_clbk(struct bv_mesh_lod *lod, int(*clbk)(struct bv_mesh_lod *, void *))
void float float * y
Definition tig.h:73
void int * c
Definition tig.h:139
void float * x
Definition tig.h:72
fastf_t vect_t[ELEMENTS_PER_VECT]
3-tuple vector
Definition vmath.h:349
double fastf_t
fastest 64-bit (or larger) floating point type
Definition vmath.h:334
fastf_t point_t[ELEMENTS_PER_POINT]
3-tuple point
Definition vmath.h:355
Definition ptbl.h:53
struct bv_mesh_lod_context_internal * i
Definition lod.h:70
struct bv_scene_obj * s
Definition defines.h:412
fundamental vector, matrix, quaternion math macros