BRL-CAD
Loading...
Searching...
No Matches
db_instance.h
Go to the documentation of this file.
1/* D B _ I N S T A N C E . H
2 * BRL-CAD
3 *
4 * Copyright (c) 1993-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/** @file db_instance.h
21 *
22 */
23
24#ifndef RT_DB_INSTANCE_H
25#define RT_DB_INSTANCE_H
26
27#include "common.h"
28
29/* system headers */
30#include <stdio.h> /* for FILE */
31
32/* interface headers */
33#include "bu/magic.h"
34#include "bu/file.h"
35#include "bu/mapped_file.h"
36#include "bu/ptbl.h"
37#include "bn/tol.h"
38#include "rt/mem.h"
39#include "rt/op.h"
40#include "rt/directory.h"
41#include "rt/anim.h"
42#include "rt/tol.h"
43
45
46struct db_i; /* forward declaration */
47struct rt_wdb; /* forward declaration */
48
49/* Callback called when database objects are changed. The int indicates
50 * the change type (0 = mod, 1 = add, 2 = rm). ctx is a user
51 * supplied context and is passed back as the last argument to db_change.
52 */
53typedef void (*dbi_changed_t)(struct db_i *, struct directory *, int, void *);
54
55
56/* Callback called when references are updated. Args are:
57 *
58 * 1. parent dp,
59 * 2. child dp referenced by parent dp
60 * 3. the child name (should be available even if the child dp is null, which can happen with references to
61 * non-existent objects)
62 * 4. the boolean operation used to include the child
63 * 5. the matrix above the child (NULL == IDN matrix)
64 * 6. dbi_u_data (generally application context set for use in these callbacks)
65 *
66 * There are two particular sets of callback args that have special significance:
67 *
68 * NULL, NULL, NULL, DB_OP_UNION, NULL == the beginning of a db_update_nref cycle
69 * NULL, NULL, NULL, DB_OP_SUBTRACT, NULL == the end of a db_update_nref cycle
70 *
71 * NOTE: the contents of the child name and matrix should be copied by the
72 * caller if they want to make use of them - they are not references to
73 * stable storage.
74 *
75 * NOTE: the parent may be a non-comb object, if extrudes or other primitives
76 * that reference other primitives are present in the .g - the caller should
77 * be aware of that when processing the results.
78 *
79 * librt only stores the reference count in d_nref, but applications may
80 * need more explicit awareness of the parent/child relationships. Since
81 * db_update_nref must be called in any case for librt to function
82 * properly, this callback lets the parent application benefit from the
83 * work db_update_nref is already doing to figure out these relationships.
84 * */
85typedef void (*dbi_update_nref_t)(struct db_i *, struct directory *, struct directory *, const char *, db_op_t, matp_t, void *);
86
87/**
88 * One of these structures is used to describe each separate instance
89 * of a BRL-CAD model database ".g" file.
90 *
91 * dbi_filepath is a C-style argv array of places to search when
92 * opening related files (such as data files for EBM solids or
93 * texture-maps). The array and strings are all dynamically
94 * allocated.
95 *
96 * Note that the current working units are specified as a conversion
97 * factor to/from millimeters (they are the 'base' in local2base and
98 * base2local) because database dimensional values are always stored
99 * as millimeters (mm). The units conversion factor only affects the
100 * display and conversion of input values. This helps prevent error
101 * accumulation and improves numerical stability when calculations are
102 * made.
103 *
104 * TODO - make a db_i_internal struct, and move all the LIBRT ONLY
105 * elements into it. That will also give us a place to do fancier
106 * database state management using things like C++ containers without
107 * bothering the public API.
108 */
109struct db_i_internal;
110struct db_i {
111 uint32_t dbi_magic; /**< @brief magic number */
113 /* THESE ELEMENTS ARE AVAILABLE FOR APPLICATIONS TO READ */
114
115 char * dbi_filename; /**< @brief file name */
116 int dbi_read_only; /**< @brief !0 => read only file */
117 double dbi_local2base; /**< @brief local2mm */
118 double dbi_base2local; /**< @brief unit conversion factors */
119 char * dbi_title; /**< @brief title from IDENT rec */
120 char ** dbi_filepath; /**< @brief search path for aux file opens (convenience var) */
122 /* THESE ELEMENTS ARE FOR LIBRT ONLY, AND MAY CHANGE */
123
124 struct directory * dbi_Head[RT_DBNHASH]; /** @brief PRIVATE: object hash table */
125 FILE * dbi_fp; /**< @brief PRIVATE: standard file pointer */
126 b_off_t dbi_eof; /**< @brief PRIVATE: End+1 pos after db_scan() */
127 size_t dbi_nrec; /**< @brief PRIVATE: # records after db_scan() */
128 int dbi_uses; /**< @brief PRIVATE: # of uses of this struct */
129 struct mem_map * dbi_freep; /**< @brief PRIVATE: map of free granules */
130 void *dbi_inmem; /**< @brief PRIVATE: ptr to in-memory copy */
131 struct animate * dbi_anroot; /**< @brief PRIVATE: heads list of anim at root lvl */
132 struct bu_mapped_file * dbi_mf; /**< @brief PRIVATE: Only in read-only mode */
133 struct bu_ptbl dbi_clients; /**< @brief PRIVATE: List of rtip's using this db_i */
134 int dbi_version; /**< @brief PRIVATE: use db_version(), is negative for flipped v4 */
135 struct rt_wdb * dbi_wdbp; /**< @brief PRIVATE: disk rt_wdb */
136 struct rt_wdb * dbi_wdbp_a; /**< @brief PRIVATE: disk append-only rt_wdb */
137 struct rt_wdb * dbi_wdbp_inmem; /**< @brief PRIVATE: inmem rt_wdb */
138 struct rt_wdb * dbi_wdbp_inmem_a; /**< @brief PRIVATE: inmem append-only rt_wdb */
139 struct bu_ptbl dbi_changed_clbks; /**< @brief PRIVATE: dbi_changed_t callbacks registered with dbi */
140 struct bu_ptbl dbi_update_nref_clbks; /**< @brief PRIVATE: dbi_update_nref_t callbacks registered with dbi */
141 int dbi_use_comb_instance_ids; /**< @brief PRIVATE: flag to enable/disable comb instance tracking in full paths */
143 struct db_i_internal *i;
145#define DBI_NULL ((struct db_i *)0)
146#define RT_CHECK_DBI(_p) BU_CKMAG(_p, DBI_MAGIC, "struct db_i")
147#define RT_CK_DBI(_p) RT_CHECK_DBI(_p)
149/* Functions for registering and unregistering callbacks with a dbip */
150extern RT_EXPORT int db_add_changed_clbk(struct db_i *dbip, dbi_changed_t c, void *u_data);
151extern RT_EXPORT int db_rm_changed_clbk(struct db_i *dbip, dbi_changed_t c, void *u_data);
153extern RT_EXPORT int db_add_update_nref_clbk(struct db_i *dbip, dbi_update_nref_t c, void *u_data);
154extern RT_EXPORT int db_rm_update_nref_clbk(struct db_i *dbip, dbi_update_nref_t c, void *u_data);
156/**
157 * for db_open(), open the specified file as read-only
158 */
159#define DB_OPEN_READONLY "r"
161/**
162 * for db_open(), open the specified file as read-write
163 */
164#define DB_OPEN_READWRITE "rw"
166/**
167 * Open the named database.
168 *
169 * The 'name' parameter specifies the file or filepath to a .g
170 * geometry database file for reading and/or writing.
171 *
172 * The 'mode' parameter specifies whether to open read-only or in
173 * read-write mode, specified via the DB_OPEN_READONLY and
174 * DB_OPEN_READWRITE symbols respectively.
175 *
176 * As a convenience, the returned db_t structure's dbi_filepath field
177 * is a C-style argv array of dirs to search when attempting to open
178 * related files (such as data files for EBM solids or texture-maps).
179 * The default values are "." and the directory containing the ".g"
180 * file. They may be overridden by setting the environment variable
181 * BRLCAD_FILE_PATH.
182 *
183 * Returns:
184 * DBI_NULL error
185 * db_i * success
186 */
187RT_EXPORT extern struct db_i *
188db_open(const char *name, const char *mode);
190/**
191 * "open" an in-memory-only database instance. this initializes a
192 * dbip for use, creating an inmem dbi_wdbp as the means to add
193 * geometry to the directory (use wdb_export_external()).
194 */
195RT_EXPORT extern struct db_i * db_open_inmem(void);
197
198/**
199 * Create a new database containing just a header record, regardless
200 * of whether the database previously existed or not, and open it for
201 * reading and writing.
202 *
203 * This routine also calls db_dirbuild(), so the caller doesn't need
204 * to.
205 *
206 * Returns:
207 * DBI_NULL on error
208 * db_i * on success
209 */
210RT_EXPORT extern struct db_i *
211db_create(const char *name, int version);
213/**
214 * creates an in-memory-only database. this is very similar to
215 * db_open_inmem() with the exception that the this routine adds a
216 * default _GLOBAL object.
217 */
218RT_EXPORT extern struct db_i * db_create_inmem(void);
220
221/**
222 * Close a database, releasing dynamic memory. Will also release the db_i
223 * struct memory itself, not just the internal struct contents. However, the
224 * actual freeing of memory Waits until last user is done - db_close is a no-op
225 * if dbi_uses is greater than 1.
226 */
227RT_EXPORT extern void db_close(struct db_i *dbip);
229
231
232#endif /* RT_DB_INSTANCE_H */
233
234/*
235 * Local Variables:
236 * tab-width: 8
237 * mode: C
238 * indent-tabs-mode: t
239 * c-file-style: "stroustrup"
240 * End:
241 * ex: shiftwidth=4 tabstop=8
242 */
Definition dvec.h:74
Header file for the BRL-CAD common definitions.
void db_close(struct db_i *dbip)
struct db_i * db_create_inmem(void)
int db_rm_update_nref_clbk(struct db_i *dbip, dbi_update_nref_t c, void *u_data)
int db_add_changed_clbk(struct db_i *dbip, dbi_changed_t c, void *u_data)
void(* dbi_changed_t)(struct db_i *, struct directory *, int, void *)
Definition db_instance.h:53
struct db_i * db_open_inmem(void)
void(* dbi_update_nref_t)(struct db_i *, struct directory *, struct directory *, const char *, db_op_t, matp_t, void *)
Definition db_instance.h:85
struct db_i * db_create(const char *name, int version)
struct db_i * db_open(const char *name, const char *mode)
int db_rm_changed_clbk(struct db_i *dbip, dbi_changed_t c, void *u_data)
int db_add_update_nref_clbk(struct db_i *dbip, dbi_update_nref_t c, void *u_data)
void int char * mode
Definition tig.h:179
void int * c
Definition tig.h:139
#define b_off_t
Definition common.h:223
#define RT_DBNHASH
hash table is an array of linked lists with this many array pointer elements (Memory use for 32-bit: ...
Definition defines.h:161
fastf_t * matp_t
pointer to a 4x4 matrix
Definition vmath.h:373
Global registry of recognized magic numbers.
db_op_t
Definition op.h:55
Definition anim.h:76
Definition ptbl.h:53
b_off_t dbi_eof
PRIVATE: End+1 pos after db_scan()
size_t dbi_nrec
PRIVATE: # records after db_scan()
double dbi_base2local
unit conversion factors
void * dbi_inmem
PRIVATE: ptr to in-memory copy.
FILE * dbi_fp
PRIVATE: object hash table.
int dbi_uses
PRIVATE: # of uses of this struct.
char ** dbi_filepath
search path for aux file opens (convenience var)
struct mem_map * dbi_freep
PRIVATE: map of free granules.
struct rt_wdb * dbi_wdbp_a
PRIVATE: disk append-only rt_wdb.
double dbi_local2base
local2mm
struct rt_wdb * dbi_wdbp_inmem
PRIVATE: inmem rt_wdb.
struct animate * dbi_anroot
PRIVATE: heads list of anim at root lvl.
struct bu_mapped_file * dbi_mf
PRIVATE: Only in read-only mode.
int dbi_read_only
!0 => read only file
int dbi_version
PRIVATE: use db_version(), is negative for flipped v4.
struct db_i_internal * i
char * dbi_filename
file name
int dbi_use_comb_instance_ids
PRIVATE: flag to enable/disable comb instance tracking in full paths.
struct bu_ptbl dbi_changed_clbks
PRIVATE: dbi_changed_t callbacks registered with dbi.
struct bu_ptbl dbi_update_nref_clbks
PRIVATE: dbi_update_nref_t callbacks registered with dbi.
struct directory * dbi_Head[RT_DBNHASH]
struct rt_wdb * dbi_wdbp
PRIVATE: disk rt_wdb.
struct rt_wdb * dbi_wdbp_inmem_a
PRIVATE: inmem append-only rt_wdb.
uint32_t dbi_magic
magic number
struct bu_ptbl dbi_clients
PRIVATE: List of rtip's using this db_i.
char * dbi_title
title from IDENT rec
Definition mem.h:37
Definition wdb.h:62