BRL-CAD
Loading...
Searching...
No Matches
defines.h
Go to the documentation of this file.
1/* D E F I N E S . H
2 * BRL-CAD
3 *
4 * Copyright (c) 2008-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/** @addtogroup ged_defines
21 *
22 * Geometry EDiting Library specific definitions.
23 *
24 */
25/** @{ */
26/** @file ged/defines.h */
27
28#ifndef GED_DEFINES_H
29#define GED_DEFINES_H
30
31#include "common.h"
32#include "bu/hash.h"
33#include "bu/list.h"
34#include "bu/process.h"
35#include "bu/vls.h"
36#include "bv/defines.h"
37#include "rt/search.h"
38#include "bv/defines.h"
39#include "bv/lod.h"
40#include "dm/fbserv.h" // for fbserv_obj
41#include "rt/wdb.h" // for struct rt_wdb
42
43
44#ifndef GED_EXPORT
45# if defined(GED_DLL_EXPORTS) && defined(GED_DLL_IMPORTS)
46# error "Only GED_DLL_EXPORTS or GED_DLL_IMPORTS can be defined, not both."
47# elif defined(GED_DLL_EXPORTS)
48# define GED_EXPORT COMPILER_DLLEXPORT
49# elif defined(GED_DLL_IMPORTS)
50# define GED_EXPORT COMPILER_DLLIMPORT
51# else
52# define GED_EXPORT
53# endif
54#endif
55
56#define GED_NULL ((struct ged *)0)
57#define GED_DISPLAY_LIST_NULL ((struct display_list *)0)
58#define GED_DRAWABLE_NULL ((struct ged_drawable *)0)
59#define GED_VIEW_NULL ((struct bview *)0)
60
61#define GED_RESULT_NULL ((void *)0)
62
63/* Sequence starts after BRLCAD_ERROR, to be compatible with
64 * BU return codes */
65#define GED_HELP 0x0002 /**< invalid specification, result contains usage */
66#define GED_MORE 0x0004 /**< incomplete specification, can specify again interactively */
67#define GED_QUIET 0x0008 /**< don't set or modify the result string */
68#define GED_UNKNOWN 0x0010 /**< argv[0] was not a known command */
69#define GED_EXIT 0x0020 /**< command is requesting a clean application shutdown */
70#define GED_OVERRIDE 0x0040 /**< used to indicate settings have been overridden */
71
72/* Check the internal GED magic */
73#define GED_CK_MAGIC(_p) BU_CKMAG(_p->i, GED_MAGIC, "ged")
74
75/* Forward declaration */
76struct ged;
78
79typedef int (*ged_func_ptr)(struct ged *, int, const char *[]);
80#define GED_FUNC_PTR_NULL ((ged_func_ptr)0)
81
82/* Callback related definitions */
83typedef void (*ged_io_func_t)(void *, int);
84typedef void (*ged_refresh_func_t)(void *);
85typedef void (*ged_create_vlist_solid_func_t)(void *, struct bv_scene_obj *);
87typedef void (*ged_destroy_vlist_func_t)(void *, unsigned int, int);
89
90/**
91 * Definition of global parallel-processing semaphores.
92 *
93 */
94#define GED_SEM_WORKER ANALYZE_SEM_LAST
95#define GED_SEM_STATS GED_SEM_WORKER+1
96#define GED_SEM_LIST GED_SEM_STATS+1
97#define GED_SEM_LAST GED_SEM_LIST+1
98
99#define GED_INITIALIZED(_gedp) ((_gedp)->dbip != NULL)
100#define GED_LOCAL2BASE(_gedp) ((_gedp)->dbip->dbi_local2base)
101#define GED_BASE2LOCAL(_gedp) ((_gedp)->dbip->dbi_base2local)
102
103
104/* FIXME: leftovers from dg.h */
105#define RT_VDRW_PREFIX "_VDRW"
106#define RT_VDRW_PREFIX_LEN 6
107#define RT_VDRW_MAXNAME 31
108#define RT_VDRW_DEF_COLOR 0xffff00
110
111struct ged_subprocess {
112 uint32_t magic; /**< @brief magic number */
113 struct bu_process *p;
114 void *chan;
116 struct ged *gedp;
117 bu_clbk_t end_clbk; /**< @brief function called when process completes */
123
124
125/* Experimental work on a high-performance in-memory representation of
126 * database, view and selection states. We want this to be visible to C++ APIs
127 * like libqtcad, so they can reflect the state of the .g hierarchy in their
128 * own structures without us or them having to make copies of the data.
129 */
130#include "ged/dbi.h"
131
133
134struct ged_cmd;
135
136/* struct details are private - use accessor functions to manipulate */
137struct ged_results;
138
139/* Need to see if we can start hiding aspects of the GED state.
140 * Define an impl container to hold internal details. */
141struct ged_impl;
142
143// TODO - in the above struct, we can hide a general callback mechanism where
144// we can allow apps (via accessor functions) to set app level pre and post
145// command execution callbacks on any command. We should also be able to
146// define the "generic" callbacks that aren't specific to just one command
147// (view refresh being the canonical example), maybe via separate functions
148// from the command specific callbacks. Goal would be to eliminate the need
149// for the command tables in libtclcad and mged in favor of setting callback
150// functions. Another tell that we're getting it right will be the ability to
151// eliminate most of the current callback hooks explicitly spelled out in the
152// ged struct.
153//
154// ged_exec will always check for a specific command's callbacks, but commands
155// can also internally check for things like the view refresh callback if the
156// command implementation knows it will need to trigger it (draw, for example,
157// should check for a view refresh callback once its work is done.) Probably
158// need to track to make sure we don't have infinite loops of callbacks calling
159// callbacks assigned at run time - it'll be a situation similar to the Qt
160// signal/slots mechanism where you can accidentally set such things up.
161// Probably want to allow more than one callback function on the same command,
162// maybe checking to prevent multiple calls to the same function getting
163// assigned by mistake.
164
165struct ged {
166 struct ged_impl *i;
168 struct db_i *dbip;
171 /*************************************************************/
172 /* Information pertaining to views and view objects . */
173 /*************************************************************/
174 /* The current view */
175 struct bview *ged_gvp;
176 /* The full set of views associated with this ged object */
178 /* Sometimes applications will supply GED views, and sometimes GED commands
179 * may create views. In the latter case, ged_close will also need to free
180 * the views. We define a container to hold those views that libged is
181 * managing, since ged_views views may belong to the application rather
182 * than GED. */
183 struct bu_ptbl ged_free_views;
184
185 /* Drawing data associated with this .g file */
187
189 void *u_data; /**< @brief User data associated with this ged instance */
190
191 /** for catching log messages */
192 struct bu_vls *ged_log;
193
195 /* @todo: add support for returning an array of objects, not just a
196 * simple string.
197 *
198 * the calling application needs to be able to distinguish the
199 * individual object names from the "ls" command without resorting
200 * to quirky string encoding or format-specific quote wrapping.
201 *
202 * want to consider whether we need a json-style dictionary, but
203 * probably a literal null-terminated array will suffice here.
204 */
205 struct bu_vls *ged_result_str;
206 struct ged_results *ged_results;
207
210 char *ged_output_script; /**< @brief script for use by the outputHandler */
212 /* Old selection data containers used by joint and brep*/
213 struct bu_hash_tbl *ged_selections; /**< @brief object name -> struct rt_object_selections */
214
215 /* FIXME -- this ugly hack needs to die. the result string should
216 * be stored before the call.
217 */
219
220
221 /* TODO: hide all callback related symbols, callback typedefs
222 * (above), and eventually most if not all of the remaining fields
223 * into an _impl structure so callers are not tightly coupled to
224 * the ged structure. access via public functions that have been
225 * given design consideration.
226 */
227
228 /* FOR LIBGED INTERNAL USE */
229 struct ged_cmd *cmds;
230 int (*add)(struct ged *gedp, const struct ged_cmd *cmd);
231 int (*del)(struct ged *gedp, const char *name);
232 int (*run)(struct ged *gedp, int ac, char *av[]);
233
234 struct bu_ptbl ged_subp; /**< @brief forked sub-processes */
236 /* Callbacks */
238 void (*ged_refresh_handler)(void *); /**< @brief function for handling refresh requests */
239 void *ged_refresh_clientdata; /**< @brief client data passed to refresh handler */
240 void (*ged_output_handler)(struct ged *, char *); /**< @brief function for handling output */
241 void (*ged_create_vlist_scene_obj_callback)(void *, struct bv_scene_obj *); /**< @brief function to call after creating a vlist to create display list for solid */
242 void (*ged_create_vlist_display_list_callback)(void *, struct display_list *); /**< @brief function to call after all vlist created that loops through creating display list for each solid */
243 void (*ged_destroy_vlist_callback)(void *, unsigned int, int); /**< @brief function to call after freeing a vlist */
246 /* Handler functions for I/O communication with asynchronous subprocess commands. There
247 * are two opaque data structures at play here, with different scopes. One is the "data"
248 * pointer passed to ged_create_io_handler, which is used to store command-specific
249 * information internal to the library (the simplest thing to do is pass ged_subprocess
250 * in as the data pointer, but if that's not enough - see for example rtcheck - this
251 * mechanism allows for more elaborate measures.
252 *
253 * The second is ged_io_data, which is set in gedp by the calling application. This is where
254 * information specific to the parent's I/O environment (which by definition the library
255 * can't know about as it is application specific) lives. It should be assigned in the
256 * applications gedp before any calls to ged_create_io_handler are made.
257 * */
260 void *ged_io_data; /**< brief caller supplied data */
261
262 /* fbserv server and I/O callbacks. These must hook into the application's event
263 * loop, and so cannot be effectively supplied by low-level libraries - the
264 * application must tell us how to tie in with the toplevel event
265 * processing system it is using (typically toolkit specific). */
266 struct fbserv_obj *ged_fbs;
267
268 // Other callbacks...
269 // Tcl command strings - these are libtclcad level callbacks that execute user supplied Tcl commands if set:
270 // gdv_callback, gdv_edit_motion_delta_callback, go_more_args_callback, go_rt_end_callback
271 //
272 // fbserv_obj: fbs_callback
273 // bv.h gv_callback (only used by MGED?)
274
275 void *ged_interp; /* Temporary - do not rely on when designing new functionality */
276
277 // Information to use when invoking a text editor.
278 int app_editors_cnt;
279 const char **app_editors;
281 struct bu_ptbl editor_opts;
282 char terminal[MAXPATHLEN];
285 // The following is used instead of environment variables to select old or new
286 // command paths. Primarily relates to the next generation drawing setup with
287 // view objects and the new BoT LoD logic.
289
290 // Container allowing calling apps to store pointers to their own data.
291 // Ged init and free routines will set up and free the table, but the
292 // contents are the apps responsibility.
294};
295
296// Create and destroy a ged container. Handles all initialization - no
297// need to call init or free using these routines.
299GED_EXPORT void ged_destroy(struct ged *);
300
301// If you create a ged container on the stack or without using create/destroy,
302// you need to call ged_init before it can be used and ged_free once you are
303// done with it.
304GED_EXPORT extern void ged_init(struct ged *gedp);
305GED_EXPORT extern void ged_free(struct ged *gedp);
306
307// Associate a callback function pointer for a command. If mode is less than
308// zero, function will be registered to run BEFORE actual cmd logic is run, and
309// if greater than zero will be registered to run AFTER the cmd logic is run.
310// If mode is zero, then it is intended to be used *during* command execution
311// and it will be up to the command's implementation to incorporate the
312// callback into its execution logic. A "BU_CLBK_DURING" will be a no-op
313// unless the command implementation logic of the libged command in question
314// utilizes it. The "search" command is an example of a command that utilizes
315// a "BU_CLBK_DURING" callback. PRE and POST callbacks are handled
316// automatically by ged_exec, and command implementations should not invoke
317// them directly. LINGER is a special case involving commands utilizing long
318// running subprocesses.
319//
320// Only one function can be registered for each pre/post command slot - an
321// assignment to a command slot that already has an assigned function will
322// result in the previous function pointer being cleared and replaced. If an
323// existing pointer has been overridden GED_OVERRIDE will be set in return
324// code. An overriding assignment will override both the function and data
325// values - a NULL data value in d will overwrite an existing non-NULL value.
326//
327// If f is NULL, any existing callback function pointer in the specified slot
328// is cleared along with its data pointer.
329//
330// d optionally associates user supplied data with the callback. The bu_clbk_t
331// function signature has two data pointers - this value will be supplied as
332// the second pointer argument. (The first will usually be the ged pointer,
333// but that is not guaranteed in the BU_CLBK_DURING and BU_CLBK_LINGER cases
334// - check the command implementation to see what data it is returning via the
335// first ptr.)
336//
337// To clear all command callbacks, iterate over the ged_cmd_list results
338// and assign NULL f values.
339GED_EXPORT extern int ged_clbk_set(struct ged *gedp, const char *cmd, int mode, bu_clbk_t f, void *d);
340
341// Method calling code can use to get the current clbk info for a specific command.
342GED_EXPORT extern int ged_clbk_get(bu_clbk_t *f, void **d, struct ged *gedp, const char *cmd, int mode);
343
344// Wrapper that utilizes internal libged capabilities to detect recursive callbacks
345// Using this is optional - caller can also use results of ged_clbk_get directly -
346// but if they wish to detect and report recursion this functionality is helpful.
348 struct bu_vls *log,
349 struct ged *gedp,
350 int limit,
351 bu_clbk_t f,
352 int ac,
353 const char **av,
354 void *u1,
355 void *u2);
356
357// Functions for associating and retrieving application context information for
358// specific dm types. Not really using this yet, but we will eventually need
359// some way to provide application contents for the dm attach command to work.
360//
361// NOTE - this API is still experimental
362GED_EXPORT extern void ged_dm_ctx_set(struct ged *gedp, const char *dm_type, void *ctx);
363GED_EXPORT extern void *ged_dm_ctx_get(struct ged *gedp, const char *dm_type);
364
365
366/* accessor functions for ged_results - calling
367 * applications should not work directly with the
368 * internals of ged_results, which are not guaranteed
369 * to stay the same.
370 * defined in ged_util.c */
371GED_EXPORT extern size_t ged_results_count(struct ged_results *results);
372GED_EXPORT extern const char *ged_results_get(struct ged_results *results, size_t index);
375
377// Call ged_close to release returned ged structure. To open and close a
378// database without creating and destroying ged structure pointers (i.e. to
379// reuse a struct) call the ged_exec_open and ged_exec_close commands rather
380// than using these functions.
381GED_EXPORT extern struct ged *ged_open(const char *dbtype,
382 const char *filename,
383 int existing_only);
384// Note that ged_close frees all memory and deletes the gedp
385GED_EXPORT extern void ged_close(struct ged *gedp);
387
388/**
389 * make sure there is a command name given
391 * @todo - where should this go?
392 */
393#define GED_CHECK_ARGC_GT_0(_gedp, _argc, _flags) \
394 if ((_argc) < 1) { \
395 int ged_check_argc_gt_0_quiet = (_flags) & GED_QUIET; \
396 if (!ged_check_argc_gt_0_quiet) { \
397 bu_vls_trunc((_gedp)->ged_result_str, 0); \
398 bu_vls_printf((_gedp)->ged_result_str, "Command name not provided on (%s:%d).", __FILE__, __LINE__); \
399 } \
400 return (_flags); \
401 }
402
403
404struct ged_cmd_impl;
405struct ged_cmd {
406 struct ged_cmd_impl *i;
407};
408
409struct ged_plugin {
410 uint32_t api_version; /* must be first in struct */
411 const struct ged_cmd ** const cmds;
413};
414
420
421struct ged_process_plugin {
422 uint32_t api_version; /* must be first in struct */
423 const struct ged_cmd_process * const p;
425
426typedef int (*ged_process_ptr)(int, const char *[]);
428/* Report any messages from libged when plugins were initially loaded.
429 * Can be important when diagnosing command errors. */
430GED_EXPORT const char * ged_init_msgs(void);
431
434
435#endif /* GED_DEFINES_H */
437/** @} */
438
439/*
440 * Local Variables:
441 * tab-width: 8
442 * mode: C
443 * indent-tabs-mode: t
444 * c-file-style: "stroustrup"
445 * End:
446 * ex: shiftwidth=4 tabstop=8
447 */
Definition dvec.h:74
Header file for the BRL-CAD common definitions.
This header holds generic routines and data structures used for TCP based communication between a fra...
int(* bu_clbk_t)(int, const char **, void *, void *)
Definition defines.h:204
struct bu_hash_tbl bu_hash_tbl
Definition hash.h:48
bu_process_io_t
Definition process.h:42
void int char * mode
Definition tig.h:179
#define MAXPATHLEN
Definition common.h:239
int ged_clbk_set(struct ged *gedp, const char *cmd, int mode, bu_clbk_t f, void *d)
void ged_close(struct ged *gedp)
int ged_clbk_get(bu_clbk_t *f, void **d, struct ged *gedp, const char *cmd, int mode)
struct ged * ged_open(const char *dbtype, const char *filename, int existing_only)
int(* ged_process_ptr)(int, const char *[])
Definition defines.h:432
void(* ged_destroy_vlist_func_t)(void *, unsigned int, int)
Definition defines.h:87
void(* ged_refresh_func_t)(void *)
Definition defines.h:84
const char * ged_results_get(struct ged_results *results, size_t index)
struct ged * ged_create(void)
void(* ged_create_vlist_solid_func_t)(void *, struct bv_scene_obj *)
Definition defines.h:85
int(* ged_func_ptr)(struct ged *, int, const char *[])
Definition defines.h:79
size_t ged_results_count(struct ged_results *results)
void ged_dm_ctx_set(struct ged *gedp, const char *dm_type, void *ctx)
void ged_results_clear(struct ged_results *results)
void ged_destroy(struct ged *)
void ged_free(struct ged *gedp)
const char * ged_init_msgs(void)
int ged_clbk_exec(struct bu_vls *log, struct ged *gedp, int limit, bu_clbk_t f, int ac, const char **av, void *u1, void *u2)
void ged_results_free(struct ged_results *results)
void(* ged_io_func_t)(void *, int)
Definition defines.h:83
void * ged_dm_ctx_get(struct ged *gedp, const char *dm_type)
void(* ged_create_vlist_display_list_func_t)(void *, struct display_list *)
Definition defines.h:86
void ged_init(struct ged *gedp)
Definition ptbl.h:53
Definition vls.h:53
struct ged_cmd_process_impl * i
Definition defines.h:424
struct ged_cmd_impl * i
Definition defines.h:412
const struct ged_cmd **const cmds
Definition defines.h:417
uint32_t api_version
Definition defines.h:416
int cmd_cnt
Definition defines.h:418
const struct ged_cmd_process *const p
Definition defines.h:429
uint32_t api_version
Definition defines.h:428
struct bu_process * p
Definition defines.h:114
int stderr_active
Definition defines.h:122
bu_clbk_t end_clbk
function called when process completes
Definition defines.h:118
uint32_t magic
magic number
Definition defines.h:113
int stdout_active
Definition defines.h:121
struct ged * gedp
Definition defines.h:117
void * chan
Definition defines.h:115
void * end_clbk_data
Definition defines.h:119
Definition defines.h:167
struct fbserv_obj * ged_fbs
Definition defines.h:271
void(* ged_output_handler)(struct ged *, char *)
function for handling output
Definition defines.h:245
struct bu_vls * ged_result_str
Definition defines.h:208
struct bu_ptbl ged_uptrs
Definition defines.h:298
int(* run)(struct ged *gedp, int ac, char *av[])
Definition defines.h:237
struct ged_cmd * cmds
Definition defines.h:234
int(* del)(struct ged *gedp, const char *name)
Definition defines.h:236
struct ged_results * ged_results
Definition defines.h:209
void(* ged_destroy_vlist_callback)(void *, unsigned int, int)
function to call after freeing a vlist
Definition defines.h:248
int ged_internal_call
Definition defines.h:222
DbiState * dbi_state
Definition defines.h:171
struct bu_vls * ged_log
Definition defines.h:194
void * vlist_ctx
Definition defines.h:249
struct ged_callback_state * ged_cbs
Definition defines.h:242
struct bview * ged_gvp
Definition defines.h:177
void(* ged_create_io_handler)(struct ged_subprocess *gp, bu_process_io_t d, ged_io_func_t callback, void *data)
Definition defines.h:263
struct bu_vls go_name
Definition defines.h:169
int new_cmd_forms
Definition defines.h:293
struct bu_ptbl editor_opts
Definition defines.h:286
struct bu_ptbl free_solids
Definition defines.h:211
void * ged_interp
Definition defines.h:280
char editor[MAXPATHLEN]
Definition defines.h:285
const char ** app_editors
Definition defines.h:284
void(* ged_delete_io_handler)(struct ged_subprocess *gp, bu_process_io_t fd)
Definition defines.h:264
void * ged_refresh_clientdata
client data passed to refresh handler
Definition defines.h:244
int(* add)(struct ged *gedp, const struct ged_cmd *cmd)
Definition defines.h:235
struct bu_ptbl terminal_opts
Definition defines.h:288
struct bu_hash_tbl * ged_selections
object name -> struct rt_object_selections
Definition defines.h:216
char terminal[MAXPATHLEN]
Definition defines.h:287
void(* ged_refresh_handler)(void *)
function for handling refresh requests
Definition defines.h:243
struct bu_ptbl ged_subp
forked sub-processes
Definition defines.h:239
char * ged_output_script
script for use by the outputHandler
Definition defines.h:213
struct bview_set ged_views
Definition defines.h:179
void(* ged_create_vlist_display_list_callback)(void *, struct display_list *)
function to call after all vlist created that loops through creating display list for each solid
Definition defines.h:247
struct db_i * dbip
Definition defines.h:170
void * ged_io_data
Definition defines.h:265
struct bu_ptbl ged_free_views
Definition defines.h:185
void * u_data
User data associated with this ged instance.
Definition defines.h:191
struct ged_impl * i
Definition defines.h:168
void(* ged_create_vlist_scene_obj_callback)(void *, struct bv_scene_obj *)
function to call after creating a vlist to create display list for solid
Definition defines.h:246
struct bv_mesh_lod_context * ged_lod
Definition defines.h:188
int app_editors_cnt
Definition defines.h:283