dbconcat adjustment

CMakeLists.txt

@@ -1728,12 +1728,14 @@ brlcad_check_dirname()
 # OpenGL headers
 if(BRLCAD_ENABLE_OPENGL)
   find_package(OpenGL)
-  if(OPENGL_INCLUDE_DIR_GL)
+  # Modern CMake FindOpenGL sets OPENGL_INCLUDE_DIR; older versions used
+  # OPENGL_INCLUDE_DIR_GL.  Accept either form so the build works with both.
+  if(OPENGL_INCLUDE_DIR_GL OR OPENGL_INCLUDE_DIR)
     config_h_append(BRLCAD "#define HAVE_GL_GL_H 1\n")
-  endif(OPENGL_INCLUDE_DIR_GL)
-  if(OPENGL_INCLUDE_DIR_GLX)
+  endif()
+  if(OPENGL_INCLUDE_DIR_GLX OR OPENGL_GLX_INCLUDE_DIR)
     config_h_append(BRLCAD "#define HAVE_GL_GLX_H 1\n")
-  endif(OPENGL_INCLUDE_DIR_GLX)
+  endif()
   if(OPENGL_USING_FRAMEWORK)
     config_h_append(BRLCAD "#define HAVE_OPENGL_GL_H 1\n")
   endif(OPENGL_USING_FRAMEWORK)

doc/asciidoc/system/man1/mged.adoc

@@ -96,8 +96,8 @@ Sets the line style: `s` for solid, `d` for dashed.
 *--faceplate*, *--no-faceplate*::
 Shows or hides the faceplate overlay.
 
-*--dlist*, *--no-dlist*::
-Enables or disables display lists for wireframe rendering.
+*--cache*, *--no-cache*::
+Enables or disables backend caches for wireframe rendering.
 
 === View and Interaction
 

doc/legal/embedded/CMakeLists.txt

@@ -36,7 +36,7 @@ brlcad_manage_files(image-hash.txt             ${DOC_DIR}/legal/embedded TRIGGER
 brlcad_manage_files(json.txt                   ${DOC_DIR}/legal/embedded TRIGGER libgcv libged)
 brlcad_manage_files(liblbfgs.txt               ${DOC_DIR}/legal/embedded TRIGGER libbg)
 brlcad_manage_files(linenoise.txt              ${DOC_DIR}/legal/embedded TRIGGER ganalyze gsh nirt)
-brlcad_manage_files(lod.txt                    ${DOC_DIR}/legal/embedded TRIGGER libbv)
+brlcad_manage_files(lod.txt                    ${DOC_DIR}/legal/embedded TRIGGER libbsg)
 brlcad_manage_files(lz4.txt                    ${DOC_DIR}/legal/embedded TRIGGER librt)
 brlcad_manage_files(marching_cubes.txt         ${DOC_DIR}/legal/embedded TRIGGER librt)
 brlcad_manage_files(msinttypes.txt             ${DOC_DIR}/legal/embedded TRIGGER libbu)

doc/legal/embedded/lod.txt

@@ -20,5 +20,5 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 IN THE SOFTWARE.
 
-file:/src/libbv/lod.cpp
+file:/src/libbsg/mesh_lod.cpp
 

include/CMakeLists.txt

@@ -3,7 +3,7 @@ add_subdirectory(bu)
 add_subdirectory(bn)
 add_subdirectory(bg)
 add_subdirectory(brep)
-add_subdirectory(bv)
+add_subdirectory(bsg)
 add_subdirectory(dm)
 add_subdirectory(gcv)
 add_subdirectory(ged)
@@ -24,7 +24,7 @@ brlcad_manage_files("bresource.h" ${INCLUDE_DIR}/brlcad)
 brlcad_manage_files("brlcad.h" ${INCLUDE_DIR}/brlcad REQUIRED libwdb)
 brlcad_manage_files("bsocket.h" ${INCLUDE_DIR}/brlcad)
 brlcad_manage_files("bu.h" ${INCLUDE_DIR}/brlcad REQUIRED libbu)
-brlcad_manage_files("bv.h" ${INCLUDE_DIR}/brlcad REQUIRED libbv)
+brlcad_manage_files("bsg.h" ${INCLUDE_DIR}/brlcad REQUIRED libbsg)
 brlcad_manage_files("common.h" ${INCLUDE_DIR}/brlcad)
 brlcad_manage_files("dm.h" ${INCLUDE_DIR}/brlcad REQUIRED libdm)
 brlcad_manage_files("fft.h" ${INCLUDE_DIR}/brlcad REQUIRED libfft)

include/analyze/nirt.h

@@ -207,12 +207,6 @@ ANALYZE_EXPORT void nirt_log(struct bu_vls *o, struct nirt_state *ns, int output
  */
 ANALYZE_EXPORT int nirt_help(struct bu_vls *h, struct nirt_state *ns, bu_opt_format_t ofmt);
 
-/**
- * Return any line segments generated by processed commands in segs.  Returns
- * number of line segments in segs, or -1 if there was an error. */
-ANALYZE_EXPORT int nirt_line_segments(struct bv_vlblock **segs, struct nirt_state *ns);
-
-
 __END_DECLS
 
 #endif /* ANALYZE_NIRT_H */

include/analyze/voxelize.h

@@ -52,6 +52,7 @@ struct voxelRegion {
 
 struct rayInfo {
     fastf_t sizeVoxel;
+    int numVoxels;
     fastf_t *fillDistances;
     struct voxelRegion *regionList;
 };

include/bg/polygon.h

@@ -34,7 +34,7 @@
 #include "vmath.h"
 #include "bu/color.h"
 #include "bn/tol.h"
-#include "bv/defines.h"
+#include "bsg/defines.h"
 #include "bg/defines.h"
 #include "bg/polygon_types.h"
 

include/bn.h

@@ -50,7 +50,7 @@
 #include "bn/msr.h"
 #include "bn/noise.h"
 #include "bn/poly.h"
-#include "bv/plot3.h"
+#include "bsg/plot3.h"
 #include "bn/multipoly.h"
 #include "bn/qmath.h"
 #include "bn/rand.h"

include/brep/cdt.h

@@ -31,7 +31,7 @@
 
 #include "common.h"
 
-#include "bv/vlist.h"
+#include "bu/vls.h"
 #include "bn/tol.h"
 #include "bg/defines.h"
 #include "brep/defines.h"
@@ -40,6 +40,7 @@ __BEGIN_DECLS
 
 /* Container that holds the state of a triangulation */
 struct ON_Brep_CDT_State;
+struct bsg_line_layer;
 
 /* Create and initialize a CDT state with default tolerances.  bv
  * must be a pointer to an ON_Brep object. */
@@ -82,19 +83,17 @@ ON_Brep_CDT_Tessellate(struct ON_Brep_CDT_State *s, int face_cnt, int *faces);
 extern BREP_EXPORT int
 ON_Brep_CDT_Status(struct ON_Brep_CDT_State *s);
 
-/* Construct a vlist plot from the tessellation.  Modes are:
+/* Append a typed line-layer plot from the tessellation.  Modes are:
  *
- * 0 - shaded 3D triangles
+ * 0 - 3D triangle preview
  * 1 - 3D triangle wireframe
  * 2 - 2D triangle wireframe (from parametric space)
  *
- * Returns 0 if vlist was successfully generated, else -1
+ * Returns 0 if the plot was successfully generated, else -1
  */
 extern BREP_EXPORT int
-ON_Brep_CDT_VList(
-    struct bv_vlblock *vbp,
-    struct bu_list *vlfree,
-    struct bu_color *c,
+ON_Brep_CDT_Plot(
+    struct bsg_line_layer *layer,
     int mode,
     struct ON_Brep_CDT_State *s);
 
@@ -139,9 +138,8 @@ ON_Brep_CDT_Mesh(
 extern BREP_EXPORT int
 brep_facecdt_plot(struct bu_vls *vls, const char *solid_name,
 	const struct bg_tess_tol *ttol, const struct bn_tol *tol,
-	const ON_Brep *brep, struct bu_list *p_vhead,
-	struct bv_vlblock *vbp, struct bu_list *vlfree,
-      	int index, int plottype, int num_points);
+	const ON_Brep *brep, struct bsg_line_layer *layer,
+	int index, int plottype, int num_points);
 
 /* Routine to capture the triangles from the fast CDT process
  * for caching */

include/bsg.h

@@ -0,0 +1,95 @@
+/*                          B S G . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Umbrella header for the BSG scene-graph library.
+ *
+ * Installed BSG headers define the public scene-graph, typed payload, render,
+ * and backend adapter surface used by the modern drawing stack.  Private
+ * storage, raw-node mutation helpers, and lifecycle internals remain confined
+ * to libbsg implementation headers under src/libbsg.
+ *
+ * Headers that explicitly describe themselves as backward-compatibility
+ * bridges are transitional: prefer their documented canonical replacements
+ * for new code.
+ */
+/** @{ */
+/* @file bsg.h */
+
+#ifndef BSG_H
+#define BSG_H
+
+#include "bsg/adc.h"
+#include "bsg/action.h"
+#include "bsg/backend_adapter.h"
+#include "bsg/backend_scene.h"
+#include "bsg/camera.h"
+#include "bsg/complexity.h"
+#include "bsg/database_source.h"
+#include "bsg/defines.h"
+#include "bsg/draw_style.h"
+#include "bsg/draw_intent.h"
+#include "bsg/edit_preview.h"
+#include "bsg/export.h"
+#include "bsg/feature.h"
+#include "bsg/field.h"
+#include "bsg/geometry.h"
+#include "bsg/group.h"
+#include "bsg/hud.h"
+#include "bsg/interaction.h"
+#include "bsg/light.h"
+#include "bsg/lod.h"
+#include "bsg/material.h"
+#include "bsg/measure.h"
+#include "bsg/node.h"
+#include "bsg/object.h"
+#include "bsg/obol_node.h"
+#include "bsg/overlay.h"
+#include "bsg/payload.h"
+#include "bsg/pick.h"
+#include "bsg/polygon.h"
+#include "bsg/render_item.h"
+#include "bsg/scene_object.h"
+#include "bsg/scene_set.h"
+#include "bsg/selection.h"
+#include "bsg/separator.h"
+#include "bsg/sensor.h"
+#include "bsg/snap.h"
+#include "bsg/snap_action.h"
+#include "bsg/state.h"
+#include "bsg/switch.h"
+#include "bsg/util.h"
+#include "bsg/visibility.h"
+#include "bsg/view_set.h"
+#include "bsg/view_state.h"
+
+#endif /* BSG_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/CMakeLists.txt

@@ -0,0 +1,69 @@
+set(
+  bsg_headers
+  adc.h
+  action.h
+  annotation.h
+  appearance.h
+  backend_scene.h
+  camera.h
+  complexity.h
+  database_source.h
+  defines.h
+  draw_style.h
+  draw_ctx.h
+  draw_intent.h
+  draw_set.h
+  draw_source.h
+  edit_preview.h
+  events.h
+  export.h
+  faceplate.h
+  feature.h
+  field.h
+  geometry.h
+  group.h
+  identity.h
+  interaction.h
+  light.h
+  lod.h
+  material.h
+  measure.h
+  node.h
+  object.h
+  obol_node.h
+  overlay.h
+  payload.h
+  pick.h
+  plot3.h
+  polygon.h
+  render.h
+  render_item.h
+  backend_adapter.h
+  hud.h
+  scene_object.h
+  scene_builder.h
+  scene_set.h
+  selection.h
+  separator.h
+  sensor.h
+  snap.h
+  snap_action.h
+  state.h
+  switch.h
+  tcl_data.h
+  util.h
+  view_set.h
+  view_scope.h
+  view_state.h
+  vlist.h
+)
+brlcad_manage_files(bsg_headers ${INCLUDE_DIR}/brlcad/bsg REQUIRED libbsg)
+
+cmakefiles(CMakeLists.txt)
+
+# Local Variables:
+# tab-width: 8
+# mode: cmake
+# indent-tabs-mode: t
+# End:
+# ex: shiftwidth=2 tabstop=8

include/bsg/action.h

@@ -0,0 +1,148 @@
+/*                       A C T I O N . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * BSG action framework.
+ *
+ * Actions are owning opaque objects applied to typed node refs.  They are the
+ * public execution model for render, backend-scene, bounds, pick, snap,
+ * measure, search, and export/write operations.  Implementations share the
+ * source-private traversal engine and receive resolved bsg_state_ref frames;
+ * public consumers do not walk raw graph nodes.
+ */
+/** @{ */
+/* @file bsg/action.h */
+
+#ifndef BSG_ACTION_H
+#define BSG_ACTION_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bu/ptbl.h"
+#include "bsg/defines.h"
+#include "bsg/node.h"
+#include "bsg/object.h"
+#include "bsg/state.h"
+
+__BEGIN_DECLS
+
+struct bsg_backend_scene;
+struct bsg_backend_scene_update_result;
+struct bsg_view;
+struct bu_list;
+struct bu_vls;
+struct bsg_export_request;
+struct bsg_export_result;
+struct bsg_measure_result;
+struct bsg_pick_result;
+struct bsg_render_batch;
+struct bsg_render_request;
+struct bsg_snap_result;
+
+typedef struct bsg_action_ref {
+    void *opaque;
+} bsg_action_ref;
+
+#define BSG_ACTION_REF_NULL_INIT { NULL }
+
+BSG_EXPORT extern bsg_action_ref bsg_action_ref_null(void);
+BSG_EXPORT extern int bsg_action_ref_is_null(bsg_action_ref action);
+BSG_EXPORT extern bsg_type_id bsg_action_ref_type(bsg_action_ref action);
+BSG_EXPORT extern void bsg_action_ref_destroy(bsg_action_ref action);
+BSG_EXPORT extern int bsg_action_apply(bsg_action_ref action,
+				       bsg_node_ref root);
+
+BSG_EXPORT extern bsg_type_id bsg_bbox_action_type(void);
+BSG_EXPORT extern bsg_type_id bsg_collect_action_type(void);
+BSG_EXPORT extern bsg_type_id bsg_render_action_type(void);
+BSG_EXPORT extern bsg_type_id bsg_backend_scene_action_type(void);
+BSG_EXPORT extern bsg_type_id bsg_pick_action_type(void);
+BSG_EXPORT extern bsg_type_id bsg_snap_action_type(void);
+BSG_EXPORT extern bsg_type_id bsg_measure_action_type(void);
+BSG_EXPORT extern bsg_type_id bsg_search_action_type(void);
+BSG_EXPORT extern bsg_type_id bsg_export_records_action_type(void);
+
+BSG_EXPORT extern bsg_action_ref bsg_bbox_action_create(void);
+BSG_EXPORT extern int bsg_bbox_action_result(bsg_action_ref action,
+					     point_t bmin,
+					     point_t bmax);
+
+BSG_EXPORT extern bsg_action_ref bsg_collect_action_create(bsg_type_id type);
+BSG_EXPORT extern size_t bsg_collect_action_count(bsg_action_ref action);
+BSG_EXPORT extern bsg_node_ref bsg_collect_action_get(bsg_action_ref action,
+						      size_t idx);
+
+BSG_EXPORT extern bsg_action_ref bsg_search_action_create(const char *name);
+BSG_EXPORT extern int bsg_search_action_set_name(bsg_action_ref action,
+						 const char *name);
+BSG_EXPORT extern size_t bsg_search_action_count(bsg_action_ref action);
+BSG_EXPORT extern bsg_node_ref bsg_search_action_get(bsg_action_ref action,
+						     size_t idx);
+
+BSG_EXPORT extern bsg_action_ref bsg_render_action_create(struct bsg_render_request *req,
+							  struct bsg_render_batch *batch);
+
+BSG_EXPORT extern bsg_action_ref bsg_backend_scene_action_create(
+	struct bsg_backend_scene *scene,
+	struct bsg_view *view,
+	unsigned int flags,
+	struct bsg_backend_scene_update_result *result,
+	struct bu_vls *diagnostics);
+
+BSG_EXPORT extern struct bsg_backend_scene *
+bsg_backend_scene_action_result(bsg_action_ref action,
+				struct bsg_backend_scene_update_result *result);
+
+BSG_EXPORT extern bsg_action_ref bsg_pick_ray_action_create(struct bsg_view *view,
+							    const point_t orig,
+							    const vect_t dir,
+							    unsigned int flags);
+BSG_EXPORT extern struct bsg_pick_result *bsg_pick_action_result(bsg_action_ref action);
+
+BSG_EXPORT extern bsg_action_ref bsg_snap_action_create(struct bsg_view *view,
+							const point_t sample,
+							double tol,
+							unsigned long long kinds,
+							struct bsg_snap_result *result);
+
+BSG_EXPORT extern bsg_action_ref bsg_measure_action_create(struct bsg_view *view,
+							   const point_t a,
+							   const point_t b,
+							   struct bsg_measure_result *result);
+
+BSG_EXPORT extern bsg_action_ref bsg_export_records_action_create(
+	const struct bsg_export_request *request,
+	struct bsg_export_result *result);
+
+__END_DECLS
+
+#endif /* BSG_ACTION_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/adc.h

@@ -17,28 +17,31 @@
  * License along with this file; see the file named COPYING for more
  * information.
  */
-/** @addtogroup bv_adc
+/** @addtogroup bsg_adc
+ *
+ * Angle/Distance Cursor functions.
+ * Canonical home; bv/adc.h is a backward-compatibility bridge.
  */
 /** @{ */
-/** @file bv/adc.h */
+/** @file bsg/adc.h */
 
-#ifndef BG_ADC_H
-#define BG_ADC_H
+#ifndef BSG_ADC_H
+#define BSG_ADC_H
 
 #include "common.h"
 #include "vmath.h"
-#include "bv/defines.h"
+#include "bsg/defines.h"
 
 __BEGIN_DECLS
 
-BV_EXPORT void adc_model_to_adc_view(struct bv_adc_state *adcs, mat_t model2view, fastf_t amax);
-BV_EXPORT void adc_grid_to_adc_view(struct bv_adc_state *adcs, mat_t model2view, fastf_t amax);
-BV_EXPORT void adc_view_to_adc_grid(struct bv_adc_state *adcs, mat_t model2view);
-BV_EXPORT void adc_reset(struct bv_adc_state *adcs, mat_t view2model, mat_t model2view);
+BSG_EXPORT void adc_model_to_adc_view(struct bsg_adc_state *adcs, mat_t model2view, fastf_t amax);
+BSG_EXPORT void adc_grid_to_adc_view(struct bsg_adc_state *adcs, mat_t model2view, fastf_t amax);
+BSG_EXPORT void adc_view_to_adc_grid(struct bsg_adc_state *adcs, mat_t model2view);
+BSG_EXPORT void adc_reset(struct bsg_adc_state *adcs, mat_t view2model, mat_t model2view);
 
 __END_DECLS
 
-#endif  /* BG_ADC_H */
+#endif  /* BSG_ADC_H */
 
 /** @} */
 /*

include/bsg/annotation.h

@@ -0,0 +1,127 @@
+/*                  A N N O T A T I O N . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief Typed annotation records shared by geometry, render, export, and
+ * backend handoff APIs.
+ */
+/** @{ */
+/* @file bsg/annotation.h */
+
+#ifndef BSG_ANNOTATION_H
+#define BSG_ANNOTATION_H
+
+#include "common.h"
+#include <stddef.h>
+#include "vmath.h"
+
+__BEGIN_DECLS
+
+typedef enum bsg_annotation_space {
+    BSG_ANNOTATION_SPACE_MODEL = 0,
+    BSG_ANNOTATION_SPACE_DISPLAY = 1
+} bsg_annotation_space;
+
+typedef enum bsg_annotation_segment_kind {
+    BSG_ANNOTATION_SEGMENT_NONE = 0,
+    BSG_ANNOTATION_SEGMENT_LINE,
+    BSG_ANNOTATION_SEGMENT_CARC,
+    BSG_ANNOTATION_SEGMENT_NURB,
+    BSG_ANNOTATION_SEGMENT_BEZIER,
+    BSG_ANNOTATION_SEGMENT_TEXT
+} bsg_annotation_segment_kind;
+
+typedef enum bsg_annotation_text_position {
+    BSG_ANNOTATION_TEXT_POS_DEFAULT = 0,
+    BSG_ANNOTATION_TEXT_POS_BOTTOM_LEFT = 1,
+    BSG_ANNOTATION_TEXT_POS_BOTTOM_CENTER = 2,
+    BSG_ANNOTATION_TEXT_POS_BOTTOM_RIGHT = 3,
+    BSG_ANNOTATION_TEXT_POS_MIDDLE_LEFT = 4,
+    BSG_ANNOTATION_TEXT_POS_MIDDLE_CENTER = 5,
+    BSG_ANNOTATION_TEXT_POS_MIDDLE_RIGHT = 6,
+    BSG_ANNOTATION_TEXT_POS_TOP_LEFT = 7,
+    BSG_ANNOTATION_TEXT_POS_TOP_CENTER = 8,
+    BSG_ANNOTATION_TEXT_POS_TOP_RIGHT = 9
+} bsg_annotation_text_position;
+
+/*
+ * Segment point indexes address the annotation record's local point table.
+ * MODEL-space consumers transform those points with model_mat.  DISPLAY-space
+ * consumers anchor the local points at the record anchor and transform them
+ * with display_mat in display units.
+ */
+struct bsg_annotation_segment {
+    bsg_annotation_segment_kind kind;
+    int reverse;
+    union {
+	struct {
+	    /** Indexes into the annotation record's local point table. */
+	    int start;
+	    int end;
+	} line;
+	struct {
+	    /** Indexes into the annotation record's local point table. */
+	    int start;
+	    int end;
+	    fastf_t radius;
+	    int center_is_left;
+	    int orientation;
+	    int center;
+	} carc;
+	struct {
+	    int order;
+	    int point_type;
+	    size_t knot_count;
+	    fastf_t *knots;
+	    size_t control_point_count;
+	    int *control_points;
+	    fastf_t *weights;
+	} nurb;
+	struct {
+	    int degree;
+	    size_t control_point_count;
+	    int *control_points;
+	} bezier;
+	struct {
+	    /** Index into the annotation record's local point table. */
+	    int ref_pt;
+	    /** bsg_annotation_text_position value; 0 leaves the point unadjusted. */
+	    int relative_position;
+	    char *text;
+	    fastf_t size;
+	    fastf_t rotation;
+	} text;
+    } data;
+};
+
+__END_DECLS
+
+#endif /* BSG_ANNOTATION_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/appearance.h

@@ -0,0 +1,217 @@
+/*                   A P P E A R A N C E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Scene appearance properties independent of material.
+ */
+/** @{ */
+/* @file bsg/appearance.h */
+
+#ifndef BSG_APPEARANCE_H
+#define BSG_APPEARANCE_H
+
+#include "common.h"
+#include "bsg/defines.h"
+#include "bsg/scene_builder.h"
+
+__BEGIN_DECLS
+
+BSG_EXPORT extern void
+bsg_scene_set_line_style(bsg_scene_ref ref, int dashed);
+
+BSG_EXPORT extern int
+bsg_scene_line_style(bsg_scene_ref ref);
+
+BSG_EXPORT extern void
+bsg_scene_set_line_width(bsg_scene_ref ref, int line_width);
+
+BSG_EXPORT extern int
+bsg_scene_line_width(bsg_scene_ref ref);
+
+BSG_EXPORT extern int
+bsg_scene_apply_appearance_settings(bsg_scene_ref ref,
+				    const struct bsg_appearance_settings *settings);
+
+BSG_EXPORT extern void
+bsg_scene_set_work_flag(bsg_scene_ref ref, int wflag);
+
+BSG_EXPORT extern void
+bsg_scene_set_legacy_color_info(bsg_scene_ref ref,
+				const unsigned char basecolor[3],
+				int user_color,
+				int default_color);
+
+BSG_EXPORT extern void
+bsg_scene_legacy_basecolor(bsg_scene_ref ref, unsigned char basecolor[3]);
+
+BSG_EXPORT extern int
+bsg_scene_legacy_user_color(bsg_scene_ref ref);
+
+BSG_EXPORT extern int
+bsg_scene_legacy_default_color(bsg_scene_ref ref);
+
+BSG_EXPORT extern void
+bsg_scene_set_legacy_uses_default_color(bsg_scene_ref ref, int default_color);
+
+BSG_EXPORT extern void
+bsg_scene_set_legacy_eval_flag(bsg_scene_ref ref, int eflag);
+
+BSG_EXPORT extern int
+bsg_scene_legacy_eval_flag(bsg_scene_ref ref);
+
+BSG_EXPORT extern void
+bsg_scene_set_legacy_region_id(bsg_scene_ref ref, int region_id);
+
+BSG_EXPORT extern int
+bsg_scene_legacy_region_id(bsg_scene_ref ref);
+
+/* -----------------------------------------------------------------------
+ * Illumination / highlight state
+ *
+ * A highlighted node is currently illuminated/selected for highlighting in
+ * the renderer.  Use these accessors in place of direct compatibility-field
+ * reads and writes.  For batch selection work, prefer the bsg_selection API;
+ * these accessors are for per-node one-shot queries.
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Set the highlight (illumination) state of @p ref.
+ * @p highlighted non-zero highlights the scene object; zero clears
+ * highlighting.
+ */
+BSG_EXPORT extern void
+bsg_scene_set_highlighted(bsg_scene_ref ref, int highlighted);
+
+/**
+ * Return non-zero if @p ref is currently highlighted.
+ */
+BSG_EXPORT extern int
+bsg_scene_highlighted(bsg_scene_ref ref);
+
+/* -----------------------------------------------------------------------
+ * Changed / dirty flag
+ *
+ * The changed flag is set by update callbacks when they regenerate geometry,
+ * signalling the renderer that cached resources are stale.
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Set the changed flag on @p ref.
+ * @p changed non-zero asserts the flag; zero clears it.
+ */
+BSG_EXPORT extern void
+bsg_scene_set_changed(bsg_scene_ref ref, int changed);
+
+/**
+ * Return the current value of the changed flag for @p ref.
+ */
+BSG_EXPORT extern int
+bsg_scene_changed(bsg_scene_ref ref);
+
+/* -----------------------------------------------------------------------
+ * Drawn-frame revision stamp
+ *
+ * This stamp is set by the renderer to the bsg_view's gv_frame_rev each time
+ * the node is drawn.  Callers can detect "was this node drawn in the most
+ * recent frame" by comparing the stamp to the view's current gv_frame_rev.
+ * This replaces the legacy full-tree visibility sweep pattern.
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Return the drawn-frame revision stamp for @p ref.
+ */
+BSG_EXPORT extern uint64_t
+bsg_scene_drawn_rev(bsg_scene_ref ref);
+
+/* -----------------------------------------------------------------------
+ * Draw mode
+ *
+ * The draw mode is stored in bsg_appearance_settings for compatibility with legacy
+ * command paths.  New code should prefer the draw-intent and render-settings
+ * layers rather than reading the raw field directly.
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Return the draw mode for @p ref.
+ */
+BSG_EXPORT extern int
+bsg_scene_dmode(bsg_scene_ref ref);
+
+/**
+ * Set the draw mode for @p ref.
+ */
+BSG_EXPORT extern void
+bsg_scene_set_dmode(bsg_scene_ref ref, int draw_mode);
+
+/* -----------------------------------------------------------------------
+ * Strict draw fallback
+ *
+ * By default, shaded and hidden-line primitive tessellation failures retain
+ * legacy interactive behavior by falling back to typed wireframe geometry.
+ * Strict fallback mode makes those failures explicit: geometry is cleared and
+ * the realization remains stale.
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Return non-zero when shaded/hidden-line tessellation failures should not
+ * fall back to wireframe geometry.
+ */
+BSG_EXPORT extern int
+bsg_scene_strict_fallback(bsg_scene_ref ref);
+
+/**
+ * Set strict shaded/hidden-line fallback behavior for @p ref.
+ */
+BSG_EXPORT extern void
+bsg_scene_set_strict_fallback(bsg_scene_ref ref, int strict_fallback);
+
+/* -----------------------------------------------------------------------
+ * Transparency (transparency)
+ *
+ * transparency is stored in bsg_appearance_settings as a fastf_t in [0.0, 1.0].
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Return the transparency value for @p ref.
+ */
+BSG_EXPORT extern fastf_t
+bsg_scene_transparency(bsg_scene_ref ref);
+
+/**
+ * Set the transparency value for @p ref (range [0.0, 1.0]).
+ */
+BSG_EXPORT extern void
+bsg_scene_set_transparency(bsg_scene_ref ref, fastf_t t);
+
+__END_DECLS
+
+#endif /* BSG_APPEARANCE_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/appearance_action.h

@@ -0,0 +1,182 @@
+/*          A P P E A R A N C E _ A C T I O N . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Resolved appearance action.
+ *
+ * `bsg_appearance_resolve` combines the active appearance stack for one
+ * drawable shape:
+ *   - backend/view defaults
+ *   - database material color on the shape
+ *   - inherited group object settings supplied by traversal
+ *   - local shape object settings
+ *   - selection/highlight state
+ *
+ * The result is stored in a `bsg_resolved_appearance` and stamped onto the
+ * `bsg_render_item` by the render collector in `bsg_render_request_collect`.
+ * Backends read the resolved appearance from the render item and MUST NOT
+ * re-derive it from node fields during drawing.
+ *
+ * Appearance layer composition
+ * ----------------------------
+ * Layers are applied in priority order (lowest to highest):
+ *   BSG_ALAY_GEOM_DEFAULT — renderer/view default style
+ *   BSG_ALAY_BASE        — database material color on the shape
+ *   BSG_ALAY_INHERITED   — group/ancestor object settings
+ *   BSG_ALAY_COMMAND     — local shape command/explicit settings
+ *   BSG_ALAY_TRANSPARENCY — resolved transparency < 1.0
+ *   BSG_ALAY_GHOSTING    — dim/phantom for objects drawn by reference
+ *   BSG_ALAY_HIDDEN_LINE — hidden-line mode (overrides display mode)
+ *   BSG_ALAY_EDIT_PREVIEW — edit-plugin preview tint (yellow-ish)
+ *   BSG_ALAY_HIGHLIGHT   — selection/illumination highlight (white)
+ *
+ * Higher-priority layers win for color, transparency, line width, and display
+ * mode.  Backends consume only the resolved result.
+ */
+/** @{ */
+/* @file bsg/appearance_action.h */
+
+#ifndef BSG_APPEARANCE_ACTION_H
+#define BSG_APPEARANCE_ACTION_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+/* -----------------------------------------------------------------------
+ * Appearance layer enum
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Appearance layer flags.
+ *
+ * These bits are OR'd into bsg_resolved_appearance::active_layers to
+ * record which appearance overrides are active for a given render item.
+ * They are NOT a priority order — they are bit flags for post-resolve
+ * queries such as "is this item being highlighted?".
+ */
+typedef enum bsg_appearance_layer {
+    /** Raw material color from the node (always set). */
+    BSG_ALAY_BASE         = 0x001,
+
+    /** Ancestor group provided an inherited color override. */
+    BSG_ALAY_INHERITED    = 0x002,
+
+    /** bsg_appearance_settings color override is active. */
+    BSG_ALAY_COMMAND      = 0x004,
+
+    /** Transparency layer: transparency < 1.0. */
+    BSG_ALAY_TRANSPARENCY = 0x008,
+
+    /** Ghosting: object is drawn at reduced opacity (phantom/reference). */
+    BSG_ALAY_GHOSTING     = 0x010,
+
+    /** Hidden-line: draw mode forces hidden-line rendering. */
+    BSG_ALAY_HIDDEN_LINE  = 0x020,
+
+    /** Edit-preview tint: active in an editor's per-tool scope. */
+    BSG_ALAY_EDIT_PREVIEW = 0x040,
+
+    /** Highlight: node is selected or otherwise highlighted. */
+    BSG_ALAY_HIGHLIGHT    = 0x080,
+
+    /**
+     * Geometry default color: the node requested the renderer's default
+     * wireframe color and no command/inherited color
+     * override applied.  Render collection supplies this color from the
+     * request render settings (bsg_render_settings::geometry_default_color).
+     */
+    BSG_ALAY_GEOM_DEFAULT = 0x100
+} bsg_appearance_layer;
+
+
+/* -----------------------------------------------------------------------
+ * Resolved appearance struct
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Fully resolved appearance for one render item.
+ *
+ * Produced by `bsg_appearance_resolve`.  The backend reads these fields
+ * directly from the `bsg_render_item` and must not re-derive them.
+ *
+ * Revision fields allow backends to detect stale cached resources:
+ * - `material_rev`: bumped by `bsg_material_set_rgb` or color overrides.
+ * - `appearance_rev`: bumped by any highlight/transparency/draw_mode change.
+ *
+ * Both revisions are per-node values copied out at resolve time; a change
+ * in either indicates the backend cache key must be invalidated.
+ */
+struct bsg_resolved_appearance {
+    /** Resolved RGB color (after all layer overrides). */
+    unsigned char   color[3];
+
+    /** Resolved transparency in [0.0, 1.0]; 1.0 = fully opaque. */
+    fastf_t         transparency;
+
+    /** Resolved draw mode (BSG_WIREFRAME / BSG_SHADED / etc.). */
+    int             draw_mode;
+
+    /** Resolved line width in pixels. */
+    int             line_width;
+
+    /** Resolved line style: 0 = solid, non-zero = dashed. */
+    int             line_style;
+
+    /** Non-zero when this draw item represents evaluated boolean output. */
+    int             evaluated_region;
+
+    /** Non-zero when the node is highlighted. */
+    int             highlighted;
+
+    /**
+     * Active layer bitmask — which appearance overrides are in effect.
+     * OR of `bsg_appearance_layer` values.
+     */
+    unsigned int    active_layers;
+
+    /** Material revision at resolve time (for backend cache invalidation). */
+    uint32_t        material_rev;
+
+    /** Appearance revision at resolve time (for backend cache invalidation). */
+    uint32_t        appearance_rev;
+};
+
+
+/* Appearance resolution is performed by libbsg render collection and exposed
+ * to public callers through bsg_render_item records. */
+
+__END_DECLS
+
+#endif /* BSG_APPEARANCE_ACTION_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/backend_adapter.h

@@ -0,0 +1,211 @@
+/*                B A C K E N D _ A D A P T E R . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Backend adapter interface — the contract between BSG render batches and a
+ * concrete drawing backend.
+ *
+ * A backend (libdm GL, swrast, qtgl, or a future Obol renderer) fills in
+ * a `bsg_backend_adapter` and attaches it to a `bsg_render_request` with
+ * bsg_render_request_set_adapter().  The renderer first resolves a
+ * `bsg_render_batch`; dispatch then calls the adapter callbacks once per
+ * resolved `bsg_render_item`.
+ *
+ * The adapter owns all backend-side state; libbsg never reads or frees it.
+ * `dmp` is the same opaque display-manager handle passed to
+ * bsg_render_request_create() and is forwarded to each callback.
+ *
+ * Null function pointers are silently skipped; a backend only needs to
+ * implement the callbacks it uses.
+ *
+ * Typical lifetime per frame:
+ *   1. Caller attaches an initialised bsg_backend_adapter* to the request.
+ *   2. bsg_render_request_collect calls begin_request(), allowing the backend
+ *      to add backend-specific batch state before item collection.
+ *   3. bsg_render_batch_dispatch calls prepare() → draw() per item.
+ *   4. bsg_render_batch_dispatch calls end_request().
+ *   5. Backend-owned caches reclaim resources not seen by the owning frame.
+ */
+/** @{ */
+/* @file bsg/backend_adapter.h */
+
+#ifndef BSG_BACKEND_ADAPTER_H
+#define BSG_BACKEND_ADAPTER_H
+
+#include "common.h"
+#include "bsg/defines.h"
+#include "bsg/render_item.h"
+
+__BEGIN_DECLS
+
+struct bsg_render_request;
+
+/* -----------------------------------------------------------------------
+ * Capability flags returned by bsg_backend_adapter::capabilities()
+ * ----------------------------------------------------------------------- */
+
+/** Backend supports per-object transparency (alpha blending). */
+#define BSG_ADAPTER_CAP_TRANSPARENCY  0x01u
+
+/** Backend can render wireframe display modes. */
+#define BSG_ADAPTER_CAP_WIREFRAME     0x02u
+
+/** Backend can render shaded (BoT/mesh) display modes. */
+#define BSG_ADAPTER_CAP_SHADED        0x04u
+
+/** Backend can render HUD / faceplate overlay items. */
+#define BSG_ADAPTER_CAP_HUD           0x08u
+
+/** Backend supports GPU-side back-to-front sort for transparent items. */
+#define BSG_ADAPTER_CAP_SORTED_ALPHA  0x10u
+
+/** Backend supports BRep/NURBS surface payload records. */
+#define BSG_ADAPTER_CAP_BREP          0x20u
+
+
+/* -----------------------------------------------------------------------
+ * Invalidation reason mask
+ *
+ * Passed to the adapter invalidate() callback so that the backend can
+ * selectively re-upload only the resources that actually changed instead
+ * of blindly discarding the entire cached representation.
+ *
+ * Multiple reasons may be OR'd together in a single invalidate() call.
+ * ----------------------------------------------------------------------- */
+
+/**
+ * The payload geometry changed (e.g. vlist rebuilt, mesh re-tessellated).
+ * Backend should re-upload vertex/index data.
+ */
+#define BSG_INVALIDATE_PAYLOAD     0x01u
+
+/**
+ * The node's material or appearance changed (color, transparency, line
+ * style/width, display mode, highlight state).
+ * Backend should update per-object uniform buffers / material state.
+ */
+#define BSG_INVALIDATE_APPEARANCE  0x02u
+
+/**
+ * The accumulated transform path changed (a parent transform matrix was
+ * edited).  Backend may need to rebuild the model matrix for the object.
+ */
+#define BSG_INVALIDATE_TRANSFORM   0x04u
+
+/**
+ * The render mode changed (draw mode switched between wireframe/shaded,
+ * hidden-line toggled, etc.).
+ * Backend should re-select or recompile the render pipeline state.
+ */
+#define BSG_INVALIDATE_RENDER_MODE 0x08u
+
+/**
+ * All backend state for the node is stale; equivalent to
+ * BSG_INVALIDATE_PAYLOAD | BSG_INVALIDATE_APPEARANCE |
+ * BSG_INVALIDATE_TRANSFORM | BSG_INVALIDATE_RENDER_MODE.
+ */
+#define BSG_INVALIDATE_ALL         0x0Fu
+
+
+/* -----------------------------------------------------------------------
+ * Adapter struct
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Backend adapter — a vtable of callbacks that a concrete drawing backend
+ * implements to consume BSG render items.
+ *
+ * All callback pointers may be NULL; missing callbacks are silently skipped.
+ * The `dmp` argument to each callback is the display-manager handle from the
+ * owning `bsg_render_request`.
+ */
+struct bsg_backend_adapter {
+    int (*begin_request)(void *dmp, struct bsg_render_request *req);
+
+    /**
+     * Prepare backend resources for @p item before the first draw call.
+     *
+     * Called by `bsg_render_batch_dispatch` for each item that is about to be
+     * drawn.  Backends use this to allocate GPU buffers, compile shaders, or
+     * upload mesh data.  May be NULL when no per-item preparation is needed.
+     *
+     * Returns non-zero on success, 0 on failure (the item will still be
+     * passed to draw() — the backend decides how to handle a prepare failure).
+     */
+    int (*prepare)(void *dmp, const struct bsg_render_item *item);
+
+    /**
+     * Issue the draw call for @p item.
+     *
+     * Called after prepare() (when set) for each item in phase order.
+     * The draw call must not modify @p item.  May be NULL (drawing
+     * is silently skipped for this backend).
+     */
+    void (*draw)(void *dmp, const struct bsg_render_item *item);
+
+    /**
+     * Mark cached backend resources for @p item as stale.
+     *
+     * Called when a node's geometry or appearance has changed and the backend
+     * needs to re-upload data on the next draw.  @p reason_mask is a bitmask
+     * of BSG_INVALIDATE_* flags describing what changed; backends should only
+     * re-upload or recompile the resources indicated by the set flags.
+     * Pass BSG_INVALIDATE_ALL when the full reason is unknown.  May be NULL.
+     */
+    void (*invalidate)(void *dmp, const struct bsg_render_item *item,
+		       unsigned int reason_mask);
+
+    /**
+     * Release all backend resources associated with @p item.
+     *
+     * Called when a source is removed from the scene.  The adapter must use
+     * the render-item source identity rather than graph-node access.  May be
+     * NULL.
+     */
+    void (*free)(void *dmp, const struct bsg_render_item *item);
+
+    /**
+     * Return the set of `BSG_ADAPTER_CAP_*` flags this backend supports.
+     *
+     * May be NULL (treated as returning 0 — no declared capabilities).
+     * `bsg_render_request_collect` records capabilities in item context;
+     * callers may use them to choose between adapters or skip unsupported
+     * render passes.
+     */
+    unsigned int (*capabilities)(void *dmp);
+
+    void (*end_request)(void *dmp, const struct bsg_render_request *req);
+};
+
+__END_DECLS
+
+#endif /* BSG_BACKEND_ADAPTER_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/backend_scene.h

@@ -0,0 +1,376 @@
+/*              B A C K E N D _ S C E N E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Retained backend-scene contract.
+ *
+ * bsg_backend_scene is an OpenInventor-style backend adapter that consumes
+ * resolved bsg_render_item records and mirrors them into a retained scene.
+ * It deliberately does not inspect private scene internals: every retained field is
+ * copied from the render item contract.
+ *
+ * A native backend or future Obol adapter can either consume the flat
+ * bsg_render_item stream directly or iterate these retained nodes.  Both paths
+ * preserve GED/BSG scene semantics; no backend owns GED commands or private
+ * BSG node layout.
+ *
+ * Obol integration is intentionally outside GED command policy.  An Obol
+ * backend should enter through a `bsg_backend_adapter` consuming render
+ * batches, or through iteration over `bsg_backend_scene_node` records.
+ */
+/** @{ */
+/* @file bsg/backend_scene.h */
+
+#ifndef BSG_BACKEND_SCENE_H
+#define BSG_BACKEND_SCENE_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bu/ptbl.h"
+#include "bu/vls.h"
+#include "bsg/backend_adapter.h"
+#include "bsg/render_item.h"
+
+__BEGIN_DECLS
+
+typedef enum bsg_backend_scene_record_kind {
+    BSG_BACKEND_SCENE_NODE_GEOMETRY = 0,
+    BSG_BACKEND_SCENE_NODE_TEXT,
+    BSG_BACKEND_SCENE_NODE_IMAGE,
+    BSG_BACKEND_SCENE_NODE_OVERLAY,
+    BSG_BACKEND_SCENE_NODE_HUD,
+    BSG_BACKEND_SCENE_NODE_CAMERA,
+    BSG_BACKEND_SCENE_NODE_LIGHT,
+    BSG_BACKEND_SCENE_NODE_CLIP_PLANE
+} bsg_backend_scene_record_kind;
+
+typedef enum bsg_backend_scene_capability_gap {
+    BSG_BACKEND_SCENE_GAP_NONE         = 0x00u,
+    BSG_BACKEND_SCENE_GAP_TRANSPARENCY = 0x01u,
+    BSG_BACKEND_SCENE_GAP_WIREFRAME    = 0x02u,
+    BSG_BACKEND_SCENE_GAP_SHADED       = 0x04u,
+    BSG_BACKEND_SCENE_GAP_HUD          = 0x08u,
+    BSG_BACKEND_SCENE_GAP_SORTED_ALPHA = 0x10u,
+    BSG_BACKEND_SCENE_GAP_BREP         = 0x20u
+} bsg_backend_scene_capability_gap;
+
+typedef enum bsg_backend_scene_adapter_kind {
+    BSG_BACKEND_SCENE_ADAPTER_EXTERNAL = 0,
+    BSG_BACKEND_SCENE_ADAPTER_RETAINED_REFERENCE,
+    BSG_BACKEND_SCENE_ADAPTER_OBOL_RESERVED
+} bsg_backend_scene_adapter_kind;
+
+struct bsg_backend_scene_camera {
+    mat_t model2view;
+    mat_t view2model;
+    mat_t projection;
+    int has_projection;
+    int viewport_width;
+    int viewport_height;
+    unsigned char background1[3];
+    unsigned char background2[3];
+};
+
+struct bsg_backend_scene_clip {
+    vect_t min;
+    vect_t max;
+    int enabled;
+};
+
+struct bsg_backend_scene_lights {
+    int enabled;
+    size_t count;
+};
+
+struct bsg_backend_scene_material {
+    unsigned char color[3];
+    fastf_t transparency;
+    int draw_mode;
+    int line_width;
+    int line_style;
+    int evaluated_region;
+    unsigned int active_layers;
+    uint32_t material_revision;
+    uint32_t appearance_revision;
+};
+
+struct bsg_backend_scene_transform {
+    mat_t model;
+    point_t bounds_center;
+    fastf_t bounds_radius;
+};
+
+struct bsg_backend_scene_geometry {
+    bsg_render_geometry_kind kind;
+    uint64_t source_identity;
+    uint64_t revision;
+    size_t element_count;
+    /* Scene-owned field snapshots copied from the render item. */
+    struct {
+	point_t *points;
+	point_t *normals;
+	int *commands;
+	int *indices;
+	size_t point_count;
+	size_t normal_count;
+	size_t command_count;
+	size_t index_count;
+    } arrays;
+    struct {
+	bsg_render_image_kind kind;
+	size_t width;
+	size_t height;
+	size_t channels;
+	unsigned char *pixels;
+	size_t pixel_count;
+	int framebuffer_mode;
+    } image;
+    struct {
+	point_t *points;
+	vect_t *normals;
+	int *indices;
+	size_t point_count;
+	size_t normal_count;
+	size_t index_count;
+	size_t face_count;
+	bsg_render_surface_normal_kind normal_kind;
+	int material_valid;
+	struct bsg_resolved_appearance material;
+    } surface;
+    struct {
+	char *text;
+	bsg_annotation_space space;
+	point_t anchor;
+	mat_t model_mat;
+	mat_t display_mat;
+	point_t *points;
+	size_t point_count;
+	struct bsg_annotation_segment *segments;
+	size_t segment_count;
+    } annotation;
+    struct bsg_render_proxy proxy;
+    bsg_payload_realization_kind realization_kind;
+    bsg_payload_realization_status realization_status;
+    bsg_payload_stale_reason stale_reason;
+};
+
+struct bsg_backend_scene_source {
+    uint64_t geometry_id;
+    uint64_t lod_id;
+    uint64_t lod_policy_id;
+    bsg_render_source_scope scope;
+    bsg_render_geometry_role geometry_role;
+    bsg_render_draw_intent draw_intent;
+    enum bsg_feature_family feature_family;
+    bsg_overlay_role overlay_role;
+    bsg_overlay_class overlay_class;
+    int non_database_source;
+    int graph_depth;
+    size_t sequence;
+    unsigned int order_flags;
+};
+
+struct bsg_backend_scene_features {
+    unsigned int flags;
+    fastf_t arrow_tip_length;
+    fastf_t arrow_tip_width;
+    int hud_feature_type;
+};
+
+struct bsg_backend_scene_text {
+    int hud_feature_type;
+    char *label;
+    point_t position;
+    point_t target;
+    int size;
+    int line_flag;
+    int anchor;
+    int arrow;
+};
+
+struct bsg_backend_scene_overlay {
+    int overlay_pass;
+    int hud_pass;
+    bsg_render_phase phase;
+    int sort_key;
+    bsg_render_overlay_geometry_kind geometry_kind;
+    struct bsg_axes axes;
+    struct bsg_grid_state grid;
+};
+
+struct bsg_backend_scene_selection {
+    int visible;
+    int force_draw;
+    int highlighted;
+    int selected;
+};
+
+struct bsg_backend_scene_lod {
+    int level;
+    int level_count;
+    uint64_t identity;
+};
+
+struct bsg_backend_scene_node {
+    uint64_t cache_identity;
+    uint64_t source_identity;
+    uint64_t payload_revision;
+    uint64_t geometry_revision;
+    uint64_t last_seen_generation;
+    uint64_t update_count;
+    uint64_t draw_count;
+    unsigned int stale;
+
+    bsg_backend_scene_record_kind scene_kind;
+    struct bsg_backend_scene_source source;
+    struct bsg_backend_scene_geometry geometry;
+    struct bsg_backend_scene_features features;
+    struct bsg_backend_scene_material material;
+    struct bsg_backend_scene_transform transform;
+    struct bsg_backend_scene_text text;
+    struct bsg_backend_scene_overlay overlay;
+    struct bsg_backend_scene_selection selection;
+    struct bsg_backend_scene_lod lod;
+    uint64_t settings_hash;
+    unsigned int request_flags;
+    unsigned int backend_capabilities;
+    unsigned int capability_gaps;
+
+    struct bsg_backend_scene_node *next;
+};
+
+struct bsg_backend_scene_stats {
+    uint64_t generation;
+    size_t node_count;
+    size_t created;
+    size_t updated;
+    size_t reused;
+    size_t removed;
+    size_t drawn;
+    size_t capability_gaps;
+};
+
+struct bsg_backend_scene;
+
+struct bsg_backend_scene_update_result {
+    int rendered;
+    struct bsg_backend_scene *scene;
+    struct bsg_backend_scene_stats stats;
+    unsigned int capabilities;
+    size_t capability_gaps;
+};
+typedef int (*bsg_backend_scene_node_cb)(const struct bsg_backend_scene_node *node,
+					 void *userdata);
+
+BSG_EXPORT extern struct bsg_backend_scene *
+bsg_backend_scene_create(void);
+
+BSG_EXPORT extern struct bsg_backend_scene *
+bsg_backend_scene_create_with_capabilities(unsigned int capabilities);
+
+BSG_EXPORT extern void
+bsg_backend_scene_destroy(struct bsg_backend_scene *scene);
+
+BSG_EXPORT extern struct bsg_backend_adapter *
+bsg_backend_scene_adapter(struct bsg_backend_scene *scene);
+
+BSG_EXPORT extern struct bsg_backend_adapter *
+bsg_backend_scene_select_adapter(bsg_backend_scene_adapter_kind kind,
+				 struct bsg_backend_scene *scene,
+				 struct bsg_backend_adapter *external,
+				 struct bu_vls *diagnostics);
+
+BSG_EXPORT extern const struct bsg_backend_scene_node *
+bsg_backend_scene_find(const struct bsg_backend_scene *scene,
+		       uint64_t cache_identity);
+
+BSG_EXPORT extern int
+bsg_backend_scene_foreach_node(const struct bsg_backend_scene *scene,
+			       bsg_backend_scene_node_cb cb,
+			       void *userdata);
+
+BSG_EXPORT extern const struct bsg_backend_scene_camera *
+bsg_backend_scene_get_camera(const struct bsg_backend_scene *scene);
+
+BSG_EXPORT extern const struct bsg_backend_scene_clip *
+bsg_backend_scene_get_clip(const struct bsg_backend_scene *scene);
+
+BSG_EXPORT extern const struct bsg_backend_scene_lights *
+bsg_backend_scene_get_lights(const struct bsg_backend_scene *scene);
+
+BSG_EXPORT extern size_t
+bsg_backend_scene_count(const struct bsg_backend_scene *scene);
+
+BSG_EXPORT extern void
+bsg_backend_scene_get_stats(const struct bsg_backend_scene *scene,
+			    struct bsg_backend_scene_stats *stats);
+
+BSG_EXPORT extern void
+bsg_backend_scene_invalidate_item(struct bsg_backend_scene *scene,
+				  const struct bsg_render_item *item,
+				  unsigned int reason_mask);
+
+BSG_EXPORT extern void
+bsg_backend_scene_release_source(struct bsg_backend_scene *scene,
+				 uint64_t source_identity);
+
+BSG_EXPORT extern unsigned int
+bsg_backend_scene_capabilities(const struct bsg_backend_scene *scene);
+
+BSG_EXPORT extern void
+bsg_backend_scene_set_capabilities(struct bsg_backend_scene *scene,
+				   unsigned int capabilities);
+
+BSG_EXPORT extern int
+bsg_backend_scene_render_request(struct bsg_view *view,
+				 struct bsg_backend_scene *scene,
+				 unsigned int flags);
+
+BSG_EXPORT extern int
+bsg_backend_scene_update(struct bsg_backend_scene *scene,
+			 struct bsg_view *view,
+			 unsigned int flags,
+			 struct bsg_backend_scene_update_result *result,
+			 struct bu_vls *diagnostics);
+
+BSG_EXPORT extern int
+bsg_backend_scene_compare_items(const struct bsg_backend_scene *scene,
+				const struct bu_ptbl *items,
+				struct bu_vls *report);
+
+BSG_EXPORT extern void
+bsg_backend_scene_diagnostics(const struct bsg_backend_scene *scene,
+			      struct bu_vls *out);
+
+__END_DECLS
+
+#endif /* BSG_BACKEND_SCENE_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/camera.h

@@ -0,0 +1,174 @@
+/*                      C A M E R A . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Camera snapshot — capture and restore bsg_view camera state.
+ *
+ * A `bsg_camera` records the subset of `bsg_view` fields that fully
+ * describe the camera: scale, perspective, aet, eye_pos, rotation matrix,
+ * center matrix, model-to-view and view-to-model matrices.
+ *
+ * bsg_camera_snapshot() extracts these fields from a live view into a
+ * freshly-allocated bsg_camera.  bsg_camera_apply() restores them.
+ * The snapshot/apply pair enables undo/redo, camera presets, and
+ * renderer-neutral camera hand-off.
+ */
+/** @{ */
+/* @file bsg/camera.h */
+
+#ifndef BSG_CAMERA_H
+#define BSG_CAMERA_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bsg/defines.h"
+#include "bsg/field.h"
+#include "bsg/node.h"
+
+__BEGIN_DECLS
+
+#define BSG_CAMERA_ORTHOGRAPHIC 0
+#define BSG_CAMERA_PERSPECTIVE  1
+
+/**
+ * Camera state snapshot.
+ *
+ * All fields are plain-value copies — no pointers to live view storage.
+ * Allocate with bsg_camera_create() or bsg_camera_snapshot(); release
+ * with bsg_camera_destroy().
+ */
+struct bsg_camera {
+    fastf_t scale;            /**< @brief gv_scale at snapshot time */
+    fastf_t perspective;      /**< @brief gv_perspective */
+    vect_t  aet;              /**< @brief azimuth / elevation / twist */
+    vect_t  eye_pos;          /**< @brief eye position in model space */
+    mat_t   rotation;         /**< @brief gv_rotation */
+    mat_t   center;           /**< @brief gv_center */
+    mat_t   model2view;       /**< @brief gv_model2view */
+    mat_t   view2model;       /**< @brief gv_view2model */
+};
+
+/**
+ * Allocate an identity camera (scale=1, perspective=0, identity matrices).
+ * Returns NULL on allocation failure.
+ */
+BSG_EXPORT extern struct bsg_camera *
+bsg_camera_create(void);
+
+/**
+ * Release a camera previously allocated by bsg_camera_create() or
+ * bsg_camera_snapshot().
+ * No-op if @p cam is NULL.
+ */
+BSG_EXPORT extern void
+bsg_camera_destroy(struct bsg_camera *cam);
+
+/**
+ * Capture the current camera state from @p v into a newly allocated
+ * bsg_camera.
+ * Returns NULL if @p v is NULL or on allocation failure.
+ */
+BSG_EXPORT extern struct bsg_camera *
+bsg_camera_snapshot(const struct bsg_view *v);
+
+/**
+ * Restore the camera state stored in @p cam to @p v.
+ * Only the camera fields (scale, perspective, aet, eye_pos, rotation,
+ * center, model2view, view2model) are written; all other view state is
+ * left unchanged.
+ * No-op if either argument is NULL.
+ */
+BSG_EXPORT extern void
+bsg_camera_apply(struct bsg_camera *cam, struct bsg_view *v);
+
+
+/* -----------------------------------------------------------------------
+ * Camera-node bindings
+ *
+ * A view can carry a persistent camera snapshot that is consulted by the
+ * render request executor.  When a camera node is bound, multi-view
+ * layouts can share a single scene root and bind per-view camera nodes
+ * without duplicating scene geometry.
+ *
+ * The view does NOT take ownership of the camera node; callers must
+ * ensure the node outlives the view or explicitly unbind it before
+ * destroying it.
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Bind camera snapshot @p cam to view @p v.
+ *
+ * The snapshot is stored as a borrowed pointer on the view.
+ * Passing NULL unbinds any previously bound camera.
+ * No-op if @p v is NULL.
+ */
+BSG_EXPORT extern void
+bsg_view_set_camera_node(struct bsg_view *v, struct bsg_camera *cam);
+
+/**
+ * Return the camera snapshot bound to view @p v, or NULL if none is bound.
+ */
+BSG_EXPORT extern struct bsg_camera *
+bsg_view_get_camera_node(const struct bsg_view *v);
+
+/**
+ * Apply the camera node bound to @p v (if any) to restore the camera
+ * state.  Equivalent to:
+ *   bsg_camera_apply(bsg_view_get_camera_node(v), v)
+ * but handles a missing camera node gracefully (no-op).
+ */
+BSG_EXPORT extern void
+bsg_view_apply_camera_node(struct bsg_view *v);
+
+BSG_EXPORT extern bsg_field_ref bsg_camera_ref_projection_field(bsg_camera_ref camera);
+BSG_EXPORT extern bsg_field_ref bsg_camera_ref_perspective_field(bsg_camera_ref camera);
+BSG_EXPORT extern bsg_field_ref bsg_camera_ref_position_field(bsg_camera_ref camera);
+BSG_EXPORT extern bsg_field_ref bsg_camera_ref_orientation_field(bsg_camera_ref camera);
+BSG_EXPORT extern bsg_field_ref bsg_camera_ref_near_distance_field(bsg_camera_ref camera);
+BSG_EXPORT extern bsg_field_ref bsg_camera_ref_far_distance_field(bsg_camera_ref camera);
+
+BSG_EXPORT extern int bsg_camera_ref_set_projection(bsg_camera_ref camera, int projection);
+BSG_EXPORT extern int bsg_camera_ref_projection(bsg_camera_ref camera);
+BSG_EXPORT extern int bsg_camera_ref_set_perspective(bsg_camera_ref camera, double perspective);
+BSG_EXPORT extern double bsg_camera_ref_perspective(bsg_camera_ref camera);
+BSG_EXPORT extern int bsg_camera_ref_set_position(bsg_camera_ref camera, const point_t position);
+BSG_EXPORT extern int bsg_camera_ref_position(bsg_camera_ref camera, point_t position);
+BSG_EXPORT extern int bsg_camera_ref_set_orientation(bsg_camera_ref camera, const mat_t orientation);
+BSG_EXPORT extern int bsg_camera_ref_orientation(bsg_camera_ref camera, mat_t orientation);
+BSG_EXPORT extern int bsg_camera_ref_set_near_distance(bsg_camera_ref camera, double distance);
+BSG_EXPORT extern double bsg_camera_ref_near_distance(bsg_camera_ref camera);
+BSG_EXPORT extern int bsg_camera_ref_set_far_distance(bsg_camera_ref camera, double distance);
+BSG_EXPORT extern double bsg_camera_ref_far_distance(bsg_camera_ref camera);
+
+__END_DECLS
+
+#endif /* BSG_CAMERA_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/complexity.h

@@ -0,0 +1,54 @@
+/*                   C O M P L E X I T Y . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Complexity and LoD-policy node fields.
+ */
+/** @{ */
+/* @file bsg/complexity.h */
+
+#ifndef BSG_COMPLEXITY_H
+#define BSG_COMPLEXITY_H
+
+#include "common.h"
+#include "bsg/field.h"
+#include "bsg/node.h"
+
+__BEGIN_DECLS
+
+BSG_EXPORT extern bsg_field_ref bsg_complexity_ref_value_field(bsg_complexity_ref complexity);
+BSG_EXPORT extern bsg_field_ref bsg_complexity_ref_curve_scale_field(bsg_complexity_ref complexity);
+BSG_EXPORT extern bsg_field_ref bsg_complexity_ref_point_scale_field(bsg_complexity_ref complexity);
+BSG_EXPORT extern bsg_field_ref bsg_complexity_ref_lod_policy_field(bsg_complexity_ref complexity);
+BSG_EXPORT extern bsg_field_ref bsg_complexity_ref_lod_level_field(bsg_complexity_ref complexity);
+
+BSG_EXPORT extern int bsg_complexity_ref_set_value(bsg_complexity_ref complexity, double value);
+BSG_EXPORT extern double bsg_complexity_ref_value(bsg_complexity_ref complexity);
+BSG_EXPORT extern int bsg_complexity_ref_set_curve_scale(bsg_complexity_ref complexity, double scale);
+BSG_EXPORT extern double bsg_complexity_ref_curve_scale(bsg_complexity_ref complexity);
+BSG_EXPORT extern int bsg_complexity_ref_set_point_scale(bsg_complexity_ref complexity, double scale);
+BSG_EXPORT extern double bsg_complexity_ref_point_scale(bsg_complexity_ref complexity);
+BSG_EXPORT extern int bsg_complexity_ref_set_lod_policy(bsg_complexity_ref complexity, int policy);
+BSG_EXPORT extern int bsg_complexity_ref_lod_policy(bsg_complexity_ref complexity);
+BSG_EXPORT extern int bsg_complexity_ref_set_lod_level(bsg_complexity_ref complexity, int level);
+BSG_EXPORT extern int bsg_complexity_ref_lod_level(bsg_complexity_ref complexity);
+
+__END_DECLS
+
+#endif /* BSG_COMPLEXITY_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/database_source.h

@@ -0,0 +1,190 @@
+/*                  D A T A B A S E _ S O U R C E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this file; see the file named COPYING for more information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Public database-source node metadata.
+ *
+ * Database-source refs are semantic bindings over node fields.  New producers
+ * should create database-source separator nodes and place realized typed
+ * geometry below them.  Existing producers may bind the same source fields to
+ * their current source node while migrating away from private realization
+ * storage.
+ */
+/** @{ */
+/* @file bsg/database_source.h */
+
+#ifndef BSG_DATABASE_SOURCE_H
+#define BSG_DATABASE_SOURCE_H
+
+#include "common.h"
+#include <stdint.h>
+#include "bsg/defines.h"
+#include "bsg/draw_intent.h"
+#include "bsg/field.h"
+#include "bsg/node.h"
+#include "bsg/object.h"
+#include "bsg/scene_builder.h"
+
+__BEGIN_DECLS
+
+typedef enum bsg_database_source_material_policy {
+    BSG_DATABASE_SOURCE_MATERIAL_INHERIT = 0,
+    BSG_DATABASE_SOURCE_MATERIAL_DATABASE,
+    BSG_DATABASE_SOURCE_MATERIAL_OVERRIDE
+} bsg_database_source_material_policy;
+
+typedef enum bsg_database_source_stale_reason {
+    BSG_DATABASE_SOURCE_STALE_NONE = 0,
+    BSG_DATABASE_SOURCE_STALE_SOURCE_CHANGED,
+    BSG_DATABASE_SOURCE_STALE_VIEW_INPUT_CHANGED,
+    BSG_DATABASE_SOURCE_STALE_SETTINGS_CHANGED,
+    BSG_DATABASE_SOURCE_STALE_FORCED,
+    BSG_DATABASE_SOURCE_STALE_UPDATE_FAILED
+} bsg_database_source_stale_reason;
+
+typedef enum bsg_database_source_realization_status {
+    BSG_DATABASE_SOURCE_REALIZATION_STALE = 0,
+    BSG_DATABASE_SOURCE_REALIZATION_CURRENT
+} bsg_database_source_realization_status;
+
+typedef enum bsg_database_source_realization_role {
+    BSG_DATABASE_SOURCE_REALIZATION_ROLE_NONE = 0,
+    BSG_DATABASE_SOURCE_REALIZATION_ROLE_CSG = 1,
+    BSG_DATABASE_SOURCE_REALIZATION_ROLE_MESH = 2
+} bsg_database_source_realization_role;
+
+struct bsg_database_source_record {
+    const char *database_path;          /**< borrowed from the source field */
+    bsg_draw_mode draw_mode;
+    bsg_database_source_material_policy material_policy;
+    uint64_t source_revision;
+    uint64_t inputs_revision;
+    uint64_t realized_source_revision;
+    uint64_t realized_inputs_revision;
+    bsg_database_source_stale_reason stale_reason;
+    uint64_t realization_identity;
+    bsg_database_source_realization_status realization_status;
+    int realization_role_flags;
+    int realization_view_dependent;
+    double realization_view_scale;
+    uint64_t realization_bot_threshold;
+    double realization_curve_scale;
+    double realization_point_scale;
+};
+
+BSG_EXPORT extern bsg_type_id bsg_database_source_type(void);
+
+BSG_EXPORT extern bsg_database_source_ref bsg_database_source_ref_null(void);
+BSG_EXPORT extern int bsg_database_source_ref_is_null(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_database_source_ref bsg_database_source_ref_create(struct bsg_view *v,
+									  const char *name);
+BSG_EXPORT extern bsg_database_source_ref bsg_database_source_ref_from_node(bsg_node_ref node);
+BSG_EXPORT extern bsg_database_source_ref bsg_database_source_ref_from_scene(bsg_scene_ref scene);
+BSG_EXPORT extern bsg_node_ref bsg_database_source_ref_as_node(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_scene_ref bsg_database_source_ref_as_scene(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_separator_ref bsg_database_source_ref_as_separator(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_is_container(bsg_database_source_ref ref);
+
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_database_path_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_draw_mode_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_material_policy_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_source_revision_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_inputs_revision_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_realized_source_revision_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_realized_inputs_revision_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_stale_reason_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_realization_identity_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_realization_status_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_realization_role_flags_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_realization_view_dependent_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_realization_view_scale_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_realization_bot_threshold_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_realization_curve_scale_field(bsg_database_source_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_database_source_ref_realization_point_scale_field(bsg_database_source_ref ref);
+
+BSG_EXPORT extern int bsg_database_source_ref_set_database_path(bsg_database_source_ref ref,
+							       const char *path);
+BSG_EXPORT extern const char *bsg_database_source_ref_database_path(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_set_draw_mode(bsg_database_source_ref ref,
+							    bsg_draw_mode mode);
+BSG_EXPORT extern bsg_draw_mode bsg_database_source_ref_draw_mode(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_set_material_policy(bsg_database_source_ref ref,
+								  bsg_database_source_material_policy policy);
+BSG_EXPORT extern bsg_database_source_material_policy
+bsg_database_source_ref_material_policy(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_set_source_revision(bsg_database_source_ref ref,
+								  uint64_t revision);
+BSG_EXPORT extern uint64_t bsg_database_source_ref_source_revision(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_set_inputs_revision(bsg_database_source_ref ref,
+								  uint64_t revision);
+BSG_EXPORT extern uint64_t bsg_database_source_ref_inputs_revision(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_set_realized_source_revision(bsg_database_source_ref ref,
+									   uint64_t revision);
+BSG_EXPORT extern uint64_t bsg_database_source_ref_realized_source_revision(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_set_realized_inputs_revision(bsg_database_source_ref ref,
+									   uint64_t revision);
+BSG_EXPORT extern uint64_t bsg_database_source_ref_realized_inputs_revision(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_set_stale_reason(bsg_database_source_ref ref,
+							       bsg_database_source_stale_reason reason);
+BSG_EXPORT extern bsg_database_source_stale_reason
+bsg_database_source_ref_stale_reason(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_set_realization_identity(bsg_database_source_ref ref,
+								       uint64_t identity);
+BSG_EXPORT extern uint64_t bsg_database_source_ref_realization_identity(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_set_realization_status(bsg_database_source_ref ref,
+								     bsg_database_source_realization_status status);
+BSG_EXPORT extern bsg_database_source_realization_status
+bsg_database_source_ref_realization_status(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_set_realization_role_flags(bsg_database_source_ref ref,
+									 int role_flags);
+BSG_EXPORT extern int bsg_database_source_ref_realization_role_flags(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_set_realization_view_policy(bsg_database_source_ref ref,
+									  int view_dependent,
+									  double view_scale,
+									  uint64_t bot_threshold,
+									  double curve_scale,
+									  double point_scale);
+BSG_EXPORT extern int bsg_database_source_ref_realization_view_dependent(bsg_database_source_ref ref);
+BSG_EXPORT extern double bsg_database_source_ref_realization_view_scale(bsg_database_source_ref ref);
+BSG_EXPORT extern uint64_t bsg_database_source_ref_realization_bot_threshold(bsg_database_source_ref ref);
+BSG_EXPORT extern double bsg_database_source_ref_realization_curve_scale(bsg_database_source_ref ref);
+BSG_EXPORT extern double bsg_database_source_ref_realization_point_scale(bsg_database_source_ref ref);
+
+BSG_EXPORT extern int bsg_database_source_ref_is_stale(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_ref_mark_realized_current(bsg_database_source_ref ref);
+BSG_EXPORT extern int bsg_database_source_record_get(bsg_database_source_ref ref,
+						     struct bsg_database_source_record *record);
+BSG_EXPORT extern int bsg_database_source_record_apply(bsg_database_source_ref ref,
+						       const struct bsg_database_source_record *record);
+
+__END_DECLS
+
+#endif /* BSG_DATABASE_SOURCE_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/defines.h

@@ -0,0 +1,483 @@
+/*                      D E F I N E S . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Canonical scene-graph and view type definitions.
+ *
+ * This header is the authoritative home for all scene-graph and view
+ * type definitions previously in bv/defines.h.  bv/defines.h is now a
+ * backward-compatibility bridge that will be removed once all callers
+ * have migrated to bsg/defines.h.
+ */
+/** @{ */
+/* @file bsg/defines.h */
+
+#ifndef BSG_DEFINES_H
+#define BSG_DEFINES_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bu/list.h"
+#include "bu/ptbl.h"
+#include "bu/vls.h"
+#include "bg/polygon_types.h"
+#include "bsg/tcl_data.h"
+#include "bsg/faceplate.h"
+
+__BEGIN_DECLS
+
+#ifndef BSG_EXPORT
+#  if defined(BSG_DLL_EXPORTS) && defined(BSG_DLL_IMPORTS)
+#    error "Only BSG_DLL_EXPORTS or BSG_DLL_IMPORTS can be defined, not both."
+#  elif defined(BSG_DLL_EXPORTS)
+#    define BSG_EXPORT COMPILER_DLLEXPORT
+#  elif defined(BSG_DLL_IMPORTS)
+#    define BSG_EXPORT COMPILER_DLLIMPORT
+#  else
+#    define BSG_EXPORT
+#  endif
+#endif
+
+/* Define view ranges.  The numbers -2048 and 2047 go all the way back to the
+ * original angle-distance cursor code that predates even BRL-CAD itself, but
+ * (at least right now) there doesn't seem to be any documentation of why those
+ * specific values were chosen. */
+#define BSG_VIEW_MAX 2047.0
+#define BSG_VIEW_MIN -2048.0
+#define BSG_VIEW_RANGE 4095.0
+/* Map +/-2048 BV space into -1.0..+1.0 :: x/2048*/
+#define BSG_INV_VIEW 0.00048828125
+#define INV_BV BSG_INV_VIEW
+#define BSG_INV_4096 0.000244140625
+#define INV_4096 0.000244140625
+
+
+#define BSG_MINVIEWSIZE 0.0001
+#define BSG_MINVIEWSCALE 0.00005
+
+#ifndef UP
+#  define UP 0
+#endif
+#ifndef DOWN
+#  define DOWN 1
+#endif
+
+#define BSG_ANCHOR_AUTO          0
+#define BSG_ANCHOR_BOTTOM_LEFT   1
+#define BSG_ANCHOR_BOTTOM_CENTER 2
+#define BSG_ANCHOR_BOTTOM_RIGHT  3
+#define BSG_ANCHOR_MIDDLE_LEFT   4
+#define BSG_ANCHOR_MIDDLE_CENTER 5
+#define BSG_ANCHOR_MIDDLE_RIGHT  6
+#define BSG_ANCHOR_TOP_LEFT      7
+#define BSG_ANCHOR_TOP_CENTER    8
+#define BSG_ANCHOR_TOP_RIGHT     9
+struct bsg_label {
+    int           size;
+    struct bu_vls label;
+    point_t       p;         // 3D base of label text
+    int           line_flag; // If 1, draw a line from label anchor to target
+    point_t       target;
+    int           anchor;    // Either closest candidate to target (AUTO), or fixed
+    int           arrow;     // If 1, use an arrow indicating direction from label to target
+};
+
+
+/* Note - this container holds information both for data axes and for the more
+ * elaborate visuals associated with the Archer style model axes.  The latter
+ * is a superset of the former, so there should be no need for a separate data
+ * type. */
+struct bsg_axes {
+    int       draw;
+    point_t   axes_pos;             /* in model coordinates */
+    fastf_t   axes_size;            /* in view coordinates for HUD drawing-mode axes */
+    int       line_width;           /* in pixels */
+    int       axes_color[3];
+
+    /* The following are (currently) only used when drawing
+     * the faceplace HUD axes */
+    int       pos_only;
+    int       label_flag;
+    int       label_color[3];
+    int       triple_color;
+    int       tick_enabled;
+    int       tick_length;          /* in pixels */
+    int       tick_major_length;    /* in pixels */
+    fastf_t   tick_interval;        /* in mm */
+    int       ticks_per_major;
+    int       tick_threshold;
+    int       tick_color[3];
+    int       tick_major_color[3];
+};
+
+/* Many settings have application level defaults that can be overridden for
+ * individual shape nodes.  Render traversal resolves these fields together
+ * with source material, command overrides, and selection/edit state into a
+ * BSG appearance action. */
+struct bsg_appearance_settings {
+
+    int draw_mode;         	/**< @brief  draw mode (legacy integer encoding; prefer the BSG_DRAW_MODE_* names):
+				 *            0 - wireframe
+				 *	      1 - shaded bots and polysolids only (booleans NOT evaluated)
+				 *	      2 - shaded (booleans NOT evaluated)
+				 *	      3 - wireframe with evaluated booleans
+				 *	      4 - hidden line
+				 *	      5 - sampled evaluated triangle points
+				 */
+    int mixed_modes;            /**< @brief  preserve other draw modes for the same source path */
+    fastf_t transparency;	/**< @brief  holds a transparency value in the range [0.0, 1.0] - 1 is opaque */
+
+    int color_override;
+    unsigned char color[3];	/**< @brief  color to draw as */
+
+    int s_line_width;		/**< @brief  current line width */
+    fastf_t s_arrow_tip_length; /**< @brief  arrow tip length */
+    fastf_t s_arrow_tip_width;  /**< @brief  arrow tip width */
+    int draw_solid_lines_only;   /**< @brief do not use dashed lines for subtraction solids */
+    int draw_non_subtract_only;  /**< @brief do not visualize subtraction solids */
+    int strict_fallback;         /**< @brief fail shaded/hidden-line realization instead of falling back to wireframe */
+};
+#define BSG_APPEARANCE_SETTINGS_INIT {0, 0, 1.0, 0, {255, 0, 0}, 1, 0.0, 0.0, 0, 0, 0}
+
+
+typedef enum bsg_geometry_role {
+    BSG_GEOMETRY_DB_OBJECT      = 0x01, /**< @brief geometry realized from a database path */
+    BSG_GEOMETRY_VIEW_OVERLAY   = 0x02, /**< @brief model-space overlay geometry */
+    BSG_GEOMETRY_LINE_SET       = 0x04, /**< @brief line-segment set geometry */
+    BSG_GEOMETRY_TEXT_LABELS    = 0x08, /**< @brief text-label geometry */
+    BSG_GEOMETRY_AXES_WIDGET    = 0x10, /**< @brief axes-widget geometry */
+    BSG_GEOMETRY_POLYGON_REGION = 0x20  /**< @brief polygon-region geometry */
+} bsg_geometry_role;
+
+struct bsg_view;
+
+typedef enum bsg_source_scope {
+    BSG_SOURCE_DB    = 0x01, /**< @brief database-backed source */
+    BSG_SOURCE_VIEW  = 0x02, /**< @brief view-scoped non-database source */
+    BSG_SOURCE_LOCAL = 0x04, /**< @brief source owned by one view/session */
+    BSG_SOURCE_CHILD = 0x08  /**< @brief internal child/group source */
+} bsg_source_scope;
+
+struct bsg_draw_intent;  /* draw-intent metadata — see bsg/draw_intent.h */
+
+/* Backend type tags used by display-manager-owned resource caches. */
+#define BSG_BACKEND_NONE 0u   /* no backend state attached */
+#define BSG_BACKEND_GL   1u   /* OpenGL/GL-via-software-rasterizer (dm-gl, dm-swrast, dm-qtgl, dm-glx, dm-wgl) */
+
+/* The primary "working" data for mesh Level-of-Detail (LoD) drawing is stored
+ * in a bsg_mesh_lod container.
+ *
+ * Most LoD information is deliberately hidden in the internal, but the key
+ * data needed for drawing routines and view setup are exposed. Although this
+ * data structure is primarily managed in libbg, the public data in this struct
+ * is needed at many levels of the software stack, including libbv. */
+struct bsg_mesh_lod {
+
+    // The set of triangle faces to be used when drawing
+    int fcnt;
+    const int *faces;
+
+    // The vertices used by the faces array
+    int pcnt;
+    const point_t *points;      // If using snapped points, that's this array.  Else, points == points_orig.
+    int porig_cnt;
+    const point_t *points_orig;
+
+    // Optional: per-face-vertex normals (one normal per triangle vertex - NOT
+    // one normal per vertex.  I.e., a given point from points_orig may have
+    // multiple normals associated with it in different faces.)
+    const vect_t *normals;
+
+    // Bounding box of the original full-detail data
+    point_t bmin;
+    point_t bmax;
+
+    // Opaque scene object handle using this LoD structure
+    void *s;
+
+    // Pointer to the higher level LoD context associated with this LoD data
+    void *c;
+
+    // Pointer to internal LoD implementation information specific to this object
+    void *i;
+};
+
+/* Flags to identify categories of objects to snap */
+#define BSG_SNAP_SHARED 0x1
+#define BSG_SNAP_LOCAL  0x2
+#define BSG_SNAP_DB     0x4
+#define BSG_SNAP_VIEW   0x8
+#define BSG_SNAP_TCL    0x10
+
+struct bsg_view_settings;
+
+/* A view needs to know what objects are active within it, but this is a
+ * function not just of adding and removing objects via commands like
+ * "draw" and "erase" but also what settings are active.  Shared objects
+ * are common to multiple views, but if adaptive plotting is enabled the
+ * scene objects cannot also be common - the representations of the objects
+ * may be different in each view, even though the object list is shared.
+ */
+struct bsg_view_obj_pool {
+    void *i; /**< @brief opaque private view scene-store handle */
+};
+
+// Data for managing "knob" manipulation of views.  One historical hardware
+// example of this "knob" concept of view manipulation would be Dial boxes such
+// as the Silicon Graphics SN-921, used with 3D workstations in the early days.
+// Although we've not heard of Dial boxes being used with BRL-CAD in many
+// years, the mathematics of view manipulation used to support them still
+// underpins interactions driven with inputs from modern peripherals such as
+// the mouse.
+struct bsg_view_knobs {
+
+    /* Rate data */
+    vect_t      rot_m;      // rotation - model coords
+    int         rot_m_flag;
+    char        origin_m;
+    void	*rot_m_udata;
+
+    vect_t	rot_o;      // rotation - object coords
+    int		rot_o_flag;
+    char	origin_o;
+    void	*rot_o_udata;
+
+    vect_t      rot_v;      // rotation - view coords
+    int         rot_v_flag;
+    char        origin_v;
+    void	*rot_v_udata;
+
+    fastf_t     sca;        // scale
+    int         sca_flag;
+    void	*sca_udata;
+
+    vect_t      tra_m;      // translation - model coords
+    int         tra_m_flag;
+    void	*tra_m_udata;
+
+    vect_t      tra_v;      // translation - view coords
+    int         tra_v_flag;
+    void	*tra_v_udata;
+
+    /* Absolute data */
+    vect_t      rot_m_abs;       // rotation - model coords
+    vect_t      rot_m_abs_last;
+
+    vect_t      rot_o_abs;       // rotation - object coords
+    vect_t      rot_o_abs_last;
+
+    vect_t      rot_v_abs;       // rotation - view coords
+    vect_t      rot_v_abs_last;
+
+    fastf_t     sca_abs;
+
+    vect_t      tra_m_abs;       // translation - model coords
+    vect_t      tra_m_abs_last;
+
+    vect_t      tra_v_abs;       // translation - view coords
+    vect_t      tra_v_abs_last;
+
+};
+
+struct bsg_view_set;
+struct bsg_camera;       /* forward decl for camera-node binding */
+
+struct bsg_view {
+    uint32_t	  magic;             /**< @brief magic number */
+    struct bu_vls gv_name;
+
+    /* Size info */
+    fastf_t       gv_i_scale;
+    fastf_t       gv_a_scale;        /**< @brief absolute scale */
+    fastf_t       gv_scale;
+    fastf_t       gv_size;           /**< @brief  2.0 * scale */
+    fastf_t       gv_isize;          /**< @brief  1.0 / size */
+    fastf_t       gv_base2local;
+    fastf_t       gv_local2base;
+    fastf_t       gv_rscale;
+    fastf_t       gv_sscale;
+
+    /* Information about current "window" into view.  This view may not be
+     * displayed (that's up to the display managers) and it is up to the
+     * calling code to set gv_width and gv_height to the current correct values
+     * for such a display, if it is associated with this view.  These
+     * definitions are needed in bsg_view to support "view aware" algorithms that
+     * require information defining an active pixel "window" into the view. */
+    int		  gv_width;
+    int		  gv_height;
+    point2d_t	  gv_wmin; // view space bbox minimum of gv_width/gv_height window
+    point2d_t	  gv_wmax; // view space bbox maximum of gv_width/gv_height window
+
+    /* Camera info */
+    fastf_t       gv_perspective;    /**< @brief  perspective angle */
+    vect_t        gv_aet;
+    vect_t        gv_eye_pos;        /**< @brief  eye position */
+    vect_t        gv_keypoint;
+    char          gv_coord;          /**< @brief  coordinate system */
+    char          gv_rotate_about;   /**< @brief  indicates what point rotations are about */
+    mat_t         gv_rotation;
+    mat_t         gv_center;
+    mat_t         gv_model2view;
+    mat_t         gv_pmodel2view;
+    mat_t         gv_view2model;
+    mat_t         gv_pmat;           /**< @brief  perspective matrix */
+
+    /* Keyboard/mouse info */
+    fastf_t       gv_prevMouseX;
+    fastf_t       gv_prevMouseY;
+    int           gv_mouse_x;
+    int           gv_mouse_y;
+    point_t       gv_prev_point;
+    point_t       gv_point;
+    char          gv_key;
+    unsigned long gv_mod_flags;
+    fastf_t       gv_minMouseDelta;
+    fastf_t       gv_maxMouseDelta;
+
+    /* Settings */
+    struct bsg_view_state *gv_state;    /**< @brief canonical command/UI view state record */
+    struct bsg_view_settings *settings_active;
+    struct bsg_view_settings *settings_local;
+
+    /* Set containing this view.  Also holds pointers to resources shared
+     * across multiple views */
+    struct bsg_view_set *vset;
+
+    /* Scene objects active in a view.  Managing these is a relatively complex
+     * topic and depends on whether a view is shared, independent or adaptive.
+     * Shared objects are common across views to make more efficient use of
+     * system memory. */
+    struct bsg_view_obj_pool gv_objs;
+
+    /* We sometimes need to define the volume in space that is "active" for the
+     * view.  For an orthogonal camera this is the oriented bounding box
+     * extruded to contain active scene objects visible in the view  The app
+     * must set the gv_bounds_update callback to bg_view_bound so a bsg_update
+     * call can update these values.*/
+    point_t obb_center;
+    vect_t obb_extent1;
+    vect_t obb_extent2;
+    vect_t obb_extent3;
+    void (*gv_bounds_update)(struct bsg_view *);
+
+    /* "Backed out" point, lookat direction, scene radius. Used for geometric
+     * view based interrogation. */
+    point_t gv_vc_backout;
+    vect_t gv_lookat;
+    double radius;
+
+    /* Knob-based view manipulation data */
+    struct bsg_view_knobs k;
+
+    /* Virtual trackball position */
+    point_t     orig_pos;
+
+    // libtclcad data (optional: NULL for non-Tcl views, allocated and owned by
+    // libtclcad tclcad_view_data when a Tcl-backed view is created)
+    struct bsg_data_tclcad *gv_tcl;
+
+    /* Callback, external data */
+    void          (*gv_callback)(struct bsg_view *, void *);  /**< @brief  called in ged_view_update with gvp and gv_clientData */
+    void           *gv_clientData;   /**< @brief  passed to gv_callback */
+    struct bu_ptbl *callbacks;
+    void           *dmp;             /* Display manager pointer, if one is associated with this view */
+    void           *u_data;          /* Caller data associated with this view */
+
+    /* Opaque scene attachment for this view.  The implementation owns the
+     * retained draw scene and the view only carries a handle to it.  The
+     * handle is intentionally opaque so application code cannot depend on
+     * implementation node identity. */
+    void           *gv_scene;
+
+    /* per-frame edit-mode matrix
+     * override.  When non-NULL, draw_scene_obj() renders edit-highlighted
+     * objects with this matrix instead of gv_model2view.  MGED sets this to
+     * view_state->vs_model2objview while the frame is being painted and
+     * clears it to NULL immediately afterward.  Never heap-allocated; always
+     * points into caller-owned storage. */
+    matp_t          gv_edit_mat;
+
+    /* Per-frame generation counter.  Bumped at the top of dm_draw_objs() so that
+     * shapes painted in the current frame can be identified by
+     * bsg_appearance_drawn_rev(shape) == gv_frame_rev without any per-frame full-tree
+     * retained-state reset sweep.  Starts at 0; first dm_draw_objs()
+     * call observes 1.  Wraps cleanly on uint64_t overflow (would take
+     * billions of years at 60 fps, but the comparison still produces
+     * the right answer for any pair of consecutive frames). */
+    uint64_t        gv_frame_rev;
+
+    /* per-view HUD scene-graph root.
+     * Stored as void * to avoid a circular include dependency.  Cast to
+     * NULL until the HUD root is created.  Contains one child per faceplate
+     * feature; bsg_hud_sync() updates each child's visibility to reflect the
+     * current bsg_view_settings before each render pass. */
+    void           *gv_hud_root;
+
+    /* bound camera snapshot for this
+     * view.  When non-NULL, bsg_view_apply_camera_node() restores the
+     * camera state from this snapshot.  Stored as a borrowed pointer
+     * (the view does NOT own the struct bsg_camera); callers must keep
+     * the camera alive for the lifetime of the binding.  NULL by default. */
+    struct bsg_camera *gv_camera_node;
+
+};
+
+// Because bsg_view instances frequently share objects in applications, they are
+// not always fully independent - we define a container and some basic
+// operations to manage this.
+struct bsg_view_set_internal;
+struct bsg_view_set {
+    struct bsg_view_set_internal   *i;
+    struct bsg_view_settings       *settings;
+};
+
+/* Export macro */
+#ifndef BSG_EXPORT
+#  if defined(BSG_DLL_EXPORTS) && defined(BSG_DLL_IMPORTS)
+#    error "Only BSG_DLL_EXPORTS or BSG_DLL_IMPORTS can be defined, not both."
+#  elif defined(BSG_DLL_EXPORTS)
+#    define BSG_EXPORT COMPILER_DLLEXPORT
+#  elif defined(BSG_DLL_IMPORTS)
+#    define BSG_EXPORT COMPILER_DLLIMPORT
+#  else
+#    define BSG_EXPORT
+#  endif
+#endif
+
+/* BSG view magic.  Numeric value matches the historical bv view magic so
+ * existing binary checks continue to work without requiring historical
+ * namespace names in BSG code. */
+#define BSG_VIEW_MAGIC 0x62766965
+
+__END_DECLS
+
+#endif /* BSG_DEFINES_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/draw_ctx.h

@@ -0,0 +1,86 @@
+/*                   D R A W _ C T X . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Draw-tree context stored on the draw-tree root.
+ *
+ * bsg_draw_ctx is a thin wrapper that lets code reach the draw-revision
+ * counter without carrying a struct ged * pointer.  The owner (libged)
+ * sets draw_rev to point at its own storage (ged_drawable::gd_draw_rev)
+ * at root-creation time.  Freeing helpers in the draw-set layer walk the
+ * parent chain to the root and bump *draw_rev through this pointer,
+ * removing the last struct ged * dependency from the BSG freeing helpers.
+ */
+/** @{ */
+/* @file bsg/draw_ctx.h */
+
+#ifndef BSG_DRAW_CTX_H
+#define BSG_DRAW_CTX_H
+
+#include "common.h"
+#include <stdint.h>
+#include "bsg/defines.h"
+#include "bsg/scene_builder.h"
+
+/**
+ * Per-root draw-tree context.  Stored on the draw root by the owner that
+ * creates the root.  Accessed (read-only pointer) by
+ * libbsg helpers that need to bump the revision counter or free objects
+ * without access to the owning application's private state.
+ *
+ * Fields:
+ *   draw_rev  - pointer to the owner's structural revision counter
+ *               (set by libged to &ged_drawable::gd_draw_rev at root
+ *               creation time).
+ *   fso       - opaque pointer to the draw-tree's private scene-node recycle
+ *               pool (set by libged via bsg_set_fsos at root creation time).
+ *               If NULL, libbsg falls back to each node's own recycle pool.
+ *   owner_data - opaque pointer reserved for the owning layer.  libbsg does
+ *               not inspect it.
+ */
+struct bsg_draw_ctx {
+    uint64_t          *draw_rev;  /**< @brief pointer to the owner's revision counter */
+    void             *fso;       /**< @brief private free-object pool handle */
+    void             *owner_data; /**< @brief opaque owner data */
+};
+
+__BEGIN_DECLS
+
+BSG_EXPORT extern void
+bsg_scene_set_draw_ctx(bsg_scene_ref ref, struct bsg_draw_ctx *ctx);
+
+BSG_EXPORT extern struct bsg_draw_ctx *
+bsg_scene_draw_ctx(bsg_scene_ref ref);
+
+__END_DECLS
+
+#endif /* BSG_DRAW_CTX_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/draw_intent.h

@@ -0,0 +1,380 @@
+/*                  D R A W _ I N T E N T . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Explicit draw-intent metadata attached to BSG scene groups.
+ *
+ * When a database draw command (e.g. "draw comb/a") creates a scene group
+ * in the BSG draw tree, a @c bsg_draw_intent record is attached to that
+ * group through scene-ref APIs.  The intent records the source
+ * path that was drawn, the draw mode (wireframe/shaded/hidden-line/etc.),
+ * the LoD policy, and whether the group is a synthetic overlay container.
+ *
+ * This replaces the old convention of:
+ *   - inferring the drawn path from the group's node name
+ *   - detecting overlay groups by comparing the node name to "_overlays"
+ *   - discovering draw mode by walking shape descendants
+ *
+ * Draw/erase semantics are now queryable through the intent API rather than
+ * reconstructed from group naming conventions and child structure.
+ *
+ * Per the draw-intent API criteria:
+ *   - Database draw/erase semantics are explicit scene metadata.
+ *   - Export/raytrace/report commands do not reconstruct command intent
+ *     from child tables or raw node fields.
+ */
+/** @{ */
+/* @file bsg/draw_intent.h */
+
+#ifndef BSG_DRAW_INTENT_H
+#define BSG_DRAW_INTENT_H
+
+#include "common.h"
+#include "bu/ptbl.h"
+#include "bu/vls.h"
+#include "bsg/defines.h"
+#include "bsg/scene_builder.h"
+
+struct bsg_view; /* forward declaration */
+struct bsg_db_event; /* forward declaration */
+
+__BEGIN_DECLS
+
+/* -----------------------------------------------------------------------
+ * Draw mode enumeration
+ *
+ * These values match the retained per-shape draw-mode storage used by
+ * bsg_appearance_settings.  New code should use BSG_DRAW_MODE_* names rather
+ * than raw integers.
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Rendering mode requested by the draw command.
+ *
+ * Numeric values are intentionally identical to the retained draw-mode field
+ * values so that existing renderers can cast freely between the two
+ * representations while both representations exist.  Some old GED parser
+ * names do not describe the modern retained behavior; prefer the semantic BSG
+ * names below for new code.
+ */
+typedef enum {
+    BSG_DRAW_MODE_WIRE         = 0,  /**< wireframe only */
+    BSG_DRAW_MODE_SHADED_BOTS  = 1,  /**< shaded BOTs/polysolids; CSG NOT evaluated */
+    BSG_DRAW_MODE_SHADED       = 2,  /**< shaded; CSG NOT evaluated */
+    BSG_DRAW_MODE_EVAL_WIRE    = 3,  /**< wireframe with evaluated booleans */
+    BSG_DRAW_MODE_HIDDEN_LINE  = 4,  /**< hidden-line removal */
+    BSG_DRAW_MODE_EVAL_POINTS  = 5   /**< sampled evaluated triangle points */
+} bsg_draw_mode;
+
+/* -----------------------------------------------------------------------
+ * LoD (Level-of-Detail) policy
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Level-of-detail policy for the drawn group.
+ */
+typedef enum {
+    BSG_DRAW_LOD_AUTO  = 0,  /**< automatic (let the renderer decide) */
+    BSG_DRAW_LOD_FORCE = 1,  /**< force LoD mesh even at close range */
+    BSG_DRAW_LOD_FULL  = 2,  /**< force full-detail tessellation */
+    BSG_DRAW_LOD_OFF   = 3   /**< LoD disabled (always draw full detail) */
+} bsg_draw_lod_policy;
+
+/* -----------------------------------------------------------------------
+ * Draw operation intent
+ *
+ * Command paths use these lightweight records to describe the requested
+ * scene mutation before GED applies it to the BSG draw graph.  The records
+ * are stack-allocatable and do not own their string pointers.
+ * ----------------------------------------------------------------------- */
+
+typedef enum {
+    BSG_DRAW_OP_NONE = 0,
+    BSG_DRAW_OP_ERASE_PATH,
+    BSG_DRAW_OP_ERASE_PATH_PREFIX,
+    BSG_DRAW_OP_ERASE_NAME,
+    BSG_DRAW_OP_CLEAR,
+    BSG_DRAW_OP_SET_TRANSPARENCY,
+    BSG_DRAW_OP_SET_DEFAULT_DRAW_MODE,
+    BSG_DRAW_OP_SET_VISIBILITY,
+    BSG_DRAW_OP_SET_HIGHLIGHT,
+    BSG_DRAW_OP_MATERIAL_CHANGED,
+    BSG_DRAW_OP_REFRESH_MATERIAL_COLORS,
+    BSG_DRAW_OP_REDRAW
+} bsg_draw_operation_kind;
+
+struct bsg_draw_operation {
+    bsg_draw_operation_kind op_kind;
+    const char *op_path;
+    double op_value;
+};
+
+BSG_EXPORT extern struct bsg_draw_operation
+bsg_draw_operation_make(bsg_draw_operation_kind kind, const char *path);
+
+BSG_EXPORT extern struct bsg_draw_operation
+bsg_draw_operation_make_value(bsg_draw_operation_kind kind, const char *path,
+			      double value);
+
+/* -----------------------------------------------------------------------
+ * bsg_draw_intent
+ *
+ * Lifecycle: bsg_draw_intent_create() / bsg_draw_intent_free().
+ * Ownership: the scene graph owns attached draw-intent records; scene teardown
+ * frees them.
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Draw-intent metadata record.
+ *
+ * Attached to BSG scene groups by the draw command when a database path
+ * is drawn.  Synthetic groups (the overlay container, etc.) are marked
+ * with @c di_overlay = 1.
+ *
+ * Fields:
+ *   di_path     — source path string as supplied to the draw command
+ *                 (e.g. "comb/a").  Never NULL on valid intents.
+ *   di_mode     — draw mode selected for this group.
+ *   di_lod      — LoD policy for this group.
+ *   di_mixed    — non-zero when mixed-mode drawing is enabled
+ *                 (do not evict objects drawn in a different mode).
+ *   di_appearance — draw-command style/fallback settings to apply when this
+ *                 intent is realized or re-expanded.
+ *   di_overlay  — non-zero when this is a synthetic overlay container
+ *                 (the "_overlays" group or similar) rather than a real
+ *                 database-path draw.
+ */
+struct bsg_draw_intent {
+    struct bu_vls  di_path;    /**< @brief drawn source path string */
+    bsg_draw_mode  di_mode;    /**< @brief draw mode */
+    bsg_draw_lod_policy di_lod;     /**< @brief LoD policy */
+    int            di_mixed;   /**< @brief mixed-mode flag */
+    struct bsg_appearance_settings di_appearance; /**< @brief draw style/fallback settings */
+    int            di_overlay; /**< @brief 1 = synthetic overlay container */
+};
+
+/* -----------------------------------------------------------------------
+ * Lifecycle
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Allocate and initialize a draw-intent for a database draw command.
+ *
+ * @p path    Source path string (copied into @c di_path).
+ * @p mode    Draw mode.
+ *
+ * Returns NULL on allocation failure.  The caller should bind the intent
+ * to a scene ref via bsg_scene_set_draw_intent().
+ */
+BSG_EXPORT extern struct bsg_draw_intent *
+bsg_draw_intent_create(const char *path, bsg_draw_mode mode);
+
+/**
+ * Allocate and initialize an overlay draw-intent.
+ *
+ * Used internally to mark the "_overlays" container.
+ * The @c di_overlay flag is set; @c di_path is set to @p name.
+ *
+ * Returns NULL on allocation failure.
+ */
+BSG_EXPORT extern struct bsg_draw_intent *
+bsg_draw_intent_create_overlay(const char *name);
+
+/**
+ * Free a draw-intent allocated by bsg_draw_intent_create() or
+ * bsg_draw_intent_create_overlay().
+ *
+ * No-op if @p di is NULL.
+ */
+BSG_EXPORT extern void
+bsg_draw_intent_free(struct bsg_draw_intent *di);
+
+BSG_EXPORT extern void
+bsg_scene_set_draw_intent(bsg_scene_ref ref, struct bsg_draw_intent *di);
+
+BSG_EXPORT extern struct bsg_draw_intent *
+bsg_scene_draw_intent(bsg_scene_ref ref);
+
+BSG_EXPORT extern int
+bsg_scene_draw_intent_revalidate(bsg_scene_ref root,
+				 const struct bsg_db_event *event);
+
+/* -----------------------------------------------------------------------
+ * Accessors
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Return the source path string from @p di (never NULL for valid intents).
+ *
+ * Returns NULL if @p di is NULL.
+ */
+BSG_EXPORT extern const char *
+bsg_draw_intent_path(const struct bsg_draw_intent *di);
+
+/**
+ * Update the source path stored in @p di.
+ *
+ * No-op if @p di is NULL.
+ */
+BSG_EXPORT extern void
+bsg_draw_intent_set_path(struct bsg_draw_intent *di, const char *path);
+
+/**
+ * Return the draw mode recorded in @p di.
+ *
+ * Returns BSG_DRAW_MODE_WIRE (0) if @p di is NULL.
+ */
+BSG_EXPORT extern bsg_draw_mode
+bsg_draw_intent_mode(const struct bsg_draw_intent *di);
+
+/**
+ * Update the draw mode stored in @p di.
+ *
+ * No-op if @p di is NULL.
+ */
+BSG_EXPORT extern void
+bsg_draw_intent_set_mode(struct bsg_draw_intent *di, bsg_draw_mode mode);
+
+/**
+ * Return the LoD policy recorded in @p di.
+ *
+ * Returns BSG_DRAW_LOD_AUTO (0) if @p di is NULL.
+ */
+BSG_EXPORT extern bsg_draw_lod_policy
+bsg_draw_intent_lod(const struct bsg_draw_intent *di);
+
+/**
+ * Copy the draw-command appearance settings recorded in @p di into @p out.
+ *
+ * Returns 1 when @p out was populated, 0 when either pointer is NULL.
+ */
+BSG_EXPORT extern int
+bsg_draw_intent_appearance(const struct bsg_draw_intent *di,
+			   struct bsg_appearance_settings *out);
+
+/**
+ * Update the draw-command appearance settings recorded in @p di.
+ *
+ * Also synchronizes @c di_mode and @c di_mixed from the supplied settings.
+ * No-op if either pointer is NULL.
+ */
+BSG_EXPORT extern void
+bsg_draw_intent_set_appearance(struct bsg_draw_intent *di,
+			       const struct bsg_appearance_settings *settings);
+
+/**
+ * Return non-zero if @p di is a synthetic overlay intent
+ * (di_overlay == 1), zero for real database-path intents.
+ *
+ * Returns 0 if @p di is NULL.
+ */
+BSG_EXPORT extern int
+bsg_draw_intent_is_overlay(const struct bsg_draw_intent *di);
+
+/* -----------------------------------------------------------------------
+ * Database event (D2)
+ *
+ * Describes a database I/O change that may affect drawn intents.
+ * Produced by libged after every modifying db_io call and consumed by
+ * bsg_draw_intent_revalidate().
+ * ----------------------------------------------------------------------- */
+
+/** Kind of database change that triggered the event. */
+typedef enum {
+    BSG_DB_EVENT_MODIFIED = 0,  /**< object contents changed */
+    BSG_DB_EVENT_REMOVED  = 1,  /**< object deleted from database */
+    BSG_DB_EVENT_RENAMED  = 2   /**< object moved/renamed (old → new path) */
+} bsg_db_event_kind;
+
+/**
+ * Lightweight value-type describing a single database change.
+ *
+ * For BSG_DB_EVENT_RENAMED, @c dbe_path holds the *new* full path and
+ * @c dbe_old_path holds the previous name.  For other kinds @c dbe_old_path
+ * is unused (set to NULL / empty).
+ *
+ * Callers may stack-allocate this struct; bsg_draw_intent_revalidate()
+ * does not retain a reference after it returns.
+ */
+struct bsg_db_event {
+    const char       *dbe_path;      /**< affected full path (new path for renames) */
+    const char       *dbe_old_path;  /**< previous path (rename only, else NULL)    */
+    bsg_db_event_kind dbe_kind;      /**< what happened                             */
+};
+
+/* -----------------------------------------------------------------------
+ * Scene-level actions
+ * ----------------------------------------------------------------------- */
+
+/* -----------------------------------------------------------------------
+ * Draw-intent action API
+ *
+ * The functions below are the primary draw-intent manipulation interface
+ * for draw-intent consumers.  Implementations live in libbsg/draw_intent.c.
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Re-evaluate every intent whose source path is affected by @p event.
+ *
+ * - BSG_DB_EVENT_MODIFIED: marks the matching intent's geometry as stale
+ *   (sets a "needs-redraw" flag on the group node).  The group is NOT
+ *   removed; callers must issue a new draw command or call the redraw
+ *   path to regenerate geometry.
+ * - BSG_DB_EVENT_REMOVED: calls bsg_draw_intent_erase_by_path() for the
+ *   affected path, removing the group from the scene.
+ * - BSG_DB_EVENT_RENAMED: updates @c di_path in the matching intent to
+ *   the new name (@c dbe_path); the group is retained in the scene.
+ *
+ * No-op if @p root or @p event is NULL, or if no matching intent exists.
+ *
+ * @returns the number of intents affected (0 = no match).
+ */
+/**
+ * Collect the intent-bearing groups under @p root that should contribute
+ * to a geometry export (rt, nirt, plot, bot_dump, …) into @p out.
+ *
+ * @p flags is a bitmask that controls which groups are included:
+ *   - BSG_EXPORT_INCLUDE_OVERLAYS (0x01) — include synthetic overlay groups.
+ *   - BSG_EXPORT_SHADED_ONLY      (0x02) — only include groups whose draw
+ *     mode is shaded or shaded-eval (exclude wireframe-only groups).
+ *
+ * @p out must be initialised by the caller.  The caller is responsible
+ * for bu_ptbl_free().
+ *
+ * No-op if @p root or @p out is NULL.
+ */
+#define BSG_EXPORT_INCLUDE_OVERLAYS 0x01ULL  /**< include overlay groups */
+#define BSG_EXPORT_SHADED_ONLY      0x02ULL  /**< shaded/eval groups only */
+
+__END_DECLS
+
+#endif /* BSG_DRAW_INTENT_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/draw_set.h

@@ -0,0 +1,241 @@
+/*                    D R A W _ S E T . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Pure-BSG draw-tree helpers that are independent of GED types.
+ *
+ * These functions operate on typed scene refs and @c struct @c bsg_view
+ * pointers.  They carry no dependency on
+ * @c struct @c ged or @c ged_private.h, making them safe to implement in
+ * libbsg.  GED-specific functionality (coloring, draw-scene callbacks,
+ * database lookups) remains in libged's GED draw-scene implementation.
+ *
+ * Together with scene refs and actions these form the tree-navigation layer
+ * used by drawing producers and command implementations.
+ */
+/** @{ */
+/* @file bsg/draw_set.h */
+
+#ifndef BSG_DRAW_SET_H
+#define BSG_DRAW_SET_H
+
+#include "common.h"
+#include "bsg/defines.h"
+#include "bsg/scene_builder.h"
+
+__BEGIN_DECLS
+
+struct bsg_view;          /* forward-declare to avoid circular includes */
+
+typedef int (*bsg_scene_path_match_fn)(bsg_scene_ref shape_ref, void *match_ctx);
+
+/**
+ * Return the depth of node @p g in its BSG tree.
+ *
+ * A node with no parent has depth 0; immediate children have depth 1; and so
+ * on.  The walk follows the @c parent pointer chain, so only nodes that are
+ * actually linked into a tree give a meaningful result.
+ *
+ * Replaces the file-private @c _sg_tree_depth() helper formerly in
+ * libged's draw-scene implementation.
+ */
+BSG_EXPORT extern int
+bsg_scene_draw_tree_depth(bsg_scene_ref ref);
+
+
+/**
+ * Find a BSG_NODE_GROUP child of @p parent named exactly @p name.
+ *
+ * Returns the matching child, or NULL when no such child exists.
+ * Does NOT create a new child if the name is absent — use
+ * bsg_group_ensure_child() for that behaviour.
+ *
+ * Replaces the linear search extracted from @c _sg_find_or_create_child_group
+ * formerly in libged's draw-scene implementation.
+ */
+BSG_EXPORT extern bsg_scene_ref
+bsg_scene_group_find_child(bsg_scene_ref parent, const char *name);
+
+
+/**
+ * Find or create a BSG_NODE_GROUP child of @p parent named @p name.
+ *
+ * When a child with the given name already exists it is returned directly.
+ * Otherwise a new BSG_NODE_GROUP node is allocated for @p v, linked into the
+ * tree, and returned.
+ *
+ * @p dp_hint is accepted for legacy call sites and ignored; database identity
+ * is owned by application-level draw-source payloads.
+ * Pass @c NULL if the caller has no corresponding database object.  For GED
+ * draw-trees the caller should pass @c (void*)dp from a prior @c db_lookup()
+ * call so that path-matching logic has a fast handle.
+ *
+ * Returns NULL on allocation failure.
+ *
+ * Replaces the @c _sg_find_or_create_child_group() helper formerly in
+ * libged's draw-scene implementation (minus the db_lookup call which belongs
+ * in the libged wrapper).
+ */
+BSG_EXPORT extern bsg_scene_ref
+bsg_scene_group_ensure_child(bsg_scene_ref parent, struct bsg_view *v,
+			     const char *name, void *dp_hint);
+
+
+/**
+ * Walk from node @p n to the draw root and bump the structural revision
+ * counter stored in the root's bsg_draw_ctx.
+ *
+ * Call on every add or remove of a group or shape node in the draw tree.
+ * Does nothing if @p n is NULL or if the root has no bsg_draw_ctx.
+ *
+ * Replaces the file-private @c _sg_bump_rev_node() helper formerly in
+ * libged's draw-scene implementation.
+ */
+BSG_EXPORT extern void
+bsg_scene_bump_rev(bsg_scene_ref ref);
+
+
+/**
+ * Recursively free all descendant nodes of @p g (shapes and nested
+ * sub-groups) without freeing @p g itself.
+ *
+ * @p fso must be the private recycle-pool handle for this draw tree.  Obtain
+ * it from the bsg_draw_ctx attached to the root (field bsg_draw_ctx::fso), or
+ * let libbsg fall back to the individual node's own recycle handle.
+ *
+ * Each freed shape node has its release callback fired before recycling.
+ * Group nodes are freed recursively.
+ *
+ * This function does NOT bump the draw-tree revision counter; callers
+ * must call bsg_bump_rev_node() at the appropriate ancestor.
+ *
+ * Replaces the file-private @c _sg_free_children_recursive() helper formerly
+ * in libged's draw-scene implementation.
+ */
+BSG_EXPORT extern void
+bsg_scene_free_group_contents(bsg_scene_ref ref);
+
+
+/**
+ * Free the entire subtree rooted at @p g, including @p g itself.
+ *
+ * Removes @p g from its parent's children table, bumps the draw-tree
+ * revision counter, then frees all descendants followed by @p g itself.
+ *
+ * It is safe to call this function on a group that has already been
+ * unlinked from its parent (parent == NULL), but in that case the
+ * revision bump is a no-op.
+ *
+ * Replaces the file-private @c _sg_free_group() helper formerly in libged's
+ * draw-scene implementation.
+ */
+BSG_EXPORT extern void
+bsg_scene_free_group(bsg_scene_ref ref);
+
+
+/**
+ * Navigate the draw sub-tree below @p parent and erase the matching
+ * sub-group or leaf shape(s) at the deepest path component.
+ *
+ * @p comp_names  Array of @p comp_count path-component name strings,
+ *                indexing from 0.  These correspond to successive BSG
+ *                group names below @p parent.
+ * @p comp_count  Total number of components in @p comp_names.
+ * @p depth_start Index into @p comp_names where navigation should begin.
+ *                Pass 0 to start from the first component; pass n to skip
+ *                the first n components (use when @p parent already
+ *                represents those n components).
+ * @p match_fn    Path-match predicate called in case (b) — the leaf
+ *                primitive case — to decide whether a BSG_NODE_SHAPE child
+ *                should be erased.  The first argument is the shape's
+ *                user-data pointer; the second is @p match_ctx.
+ *                If NULL, every BSG_NODE_SHAPE child at the leaf level is
+ *                erased.
+ * @p match_ctx   Opaque context forwarded verbatim to @p match_fn.
+ *
+ * Two cases at the final component:
+ *   a) A BSG_NODE_GROUP child with that name exists — its entire sub-tree
+ *      is freed and the group node is removed from its parent.
+ *   b) No matching group — the component is treated as a leaf primitive;
+ *      all BSG_NODE_SHAPE children that satisfy @p match_fn are freed.
+ *
+ * The structural revision counter is bumped for each erasure.
+ *
+ * Extracted from the file-private @c _sg_erase_nested_subpath() helper in
+ * src/libged/bsg_ged_draw.c.
+ */
+BSG_EXPORT extern void
+bsg_scene_erase_nested_subpath(bsg_scene_ref parent,
+			       const char * const *comp_names,
+			       size_t comp_count,
+			       size_t depth_start,
+			       bsg_scene_path_match_fn match_fn,
+			       void *match_ctx);
+
+
+/* ------------------------------------------------------------------ */
+/* Subtree bbox cache                        */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Mark the cached aggregate bbox for @p ref and its ancestors stale.
+ *
+ * Call this whenever subtree structure or bounds change.
+ */
+BSG_EXPORT extern void
+bsg_scene_bbox_invalidate(bsg_scene_ref ref);
+
+
+/**
+ * Compute the aggregate axis-aligned bbox of the subtree rooted at @p ref
+ * and store the result in (*@p min, *@p max).
+ *
+ * When @p include_overlays is 0 (the common case), overlay-only shapes are
+ * skipped and implementation caches may be used.
+ *
+ * When @p include_overlays is non-zero the cache is bypassed and a
+ * full walk is performed (overlay shapes are included).  This path is
+ * not cached because the caller is the rare include-overlays case.
+ *
+ * Returns 1 if the subtree contributes nothing to the bbox (empty),
+ * 0 otherwise.  When the subtree is empty (*@p min, *@p max) are set
+ * to (+INFINITY, -INFINITY) — the caller should treat the result as
+ * undefined unless the return value indicates non-empty.
+ */
+BSG_EXPORT extern int
+bsg_scene_subtree_bbox(bsg_scene_ref ref,
+		       vect_t *min, vect_t *max,
+		       int include_overlays);
+
+
+__END_DECLS
+
+#endif /* BSG_DRAW_SET_H */
+
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/draw_source.h

@@ -0,0 +1,96 @@
+/*                  D R A W _ S O U R C E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Draw-source accessors for graph-associated view, draw matrices, bounds,
+ * and source-realization metadata.
+ *
+ * Drawing producers use these accessors to describe their intent in BSG
+ * scene-graph terms instead of writing private view and draw-node fields.
+ */
+/** @{ */
+/* @file bsg/draw_source.h */
+
+#ifndef BSG_DRAW_SOURCE_H
+#define BSG_DRAW_SOURCE_H
+
+#include "common.h"
+#include "bu/list.h"
+#include "vmath.h"
+#include "bsg/defines.h"
+#include "bsg/scene_builder.h"
+
+__BEGIN_DECLS
+
+/* -----------------------------------------------------------------------
+ * Associated view
+ *
+ * A scene element may retain its creating/editing bsg_view.  In a multi-view
+ * scenario the view association may be updated as the element is edited from
+ * different views.
+ * ----------------------------------------------------------------------- */
+
+/* -----------------------------------------------------------------------
+ * Draw matrix
+ *
+ * The draw matrix is the 4x4 matrix used for internal lookup and mesh LoD
+ * drawing.  It is distinct from the authored scene transform.
+ * ----------------------------------------------------------------------- */
+
+/* -----------------------------------------------------------------------
+ * Bounding sphere
+ *
+ * The bounding sphere stores the model-space radius and center maintained by
+ * bsg_scene_node_update_bounds().
+ * ----------------------------------------------------------------------- */
+
+BSG_EXPORT extern void
+bsg_scene_set_draw_mat(bsg_scene_ref ref, const mat_t mat);
+
+BSG_EXPORT extern void
+bsg_scene_draw_mat(bsg_scene_ref ref, mat_t mat);
+
+BSG_EXPORT extern fastf_t
+bsg_scene_draw_size(bsg_scene_ref ref);
+
+BSG_EXPORT extern void
+bsg_scene_set_draw_size(bsg_scene_ref ref, fastf_t size);
+
+BSG_EXPORT extern void
+bsg_scene_draw_center(bsg_scene_ref ref, vect_t center);
+
+BSG_EXPORT extern void
+bsg_scene_set_draw_center(bsg_scene_ref ref, const vect_t center);
+
+__END_DECLS
+
+#endif /* BSG_DRAW_SOURCE_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/draw_style.h

@@ -0,0 +1,54 @@
+/*                   D R A W _ S T Y L E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Draw-style node fields.
+ */
+/** @{ */
+/* @file bsg/draw_style.h */
+
+#ifndef BSG_DRAW_STYLE_H
+#define BSG_DRAW_STYLE_H
+
+#include "common.h"
+#include "bsg/field.h"
+#include "bsg/node.h"
+
+__BEGIN_DECLS
+
+BSG_EXPORT extern bsg_field_ref bsg_draw_style_ref_line_width_field(bsg_draw_style_ref style);
+BSG_EXPORT extern bsg_field_ref bsg_draw_style_ref_line_style_field(bsg_draw_style_ref style);
+BSG_EXPORT extern bsg_field_ref bsg_draw_style_ref_fill_mode_field(bsg_draw_style_ref style);
+BSG_EXPORT extern bsg_field_ref bsg_draw_style_ref_point_size_field(bsg_draw_style_ref style);
+BSG_EXPORT extern bsg_field_ref bsg_draw_style_ref_transparency_policy_field(bsg_draw_style_ref style);
+
+BSG_EXPORT extern int bsg_draw_style_ref_set_line_width(bsg_draw_style_ref style, int line_width);
+BSG_EXPORT extern int bsg_draw_style_ref_line_width(bsg_draw_style_ref style);
+BSG_EXPORT extern int bsg_draw_style_ref_set_line_style(bsg_draw_style_ref style, int line_style);
+BSG_EXPORT extern int bsg_draw_style_ref_line_style(bsg_draw_style_ref style);
+BSG_EXPORT extern int bsg_draw_style_ref_set_fill_mode(bsg_draw_style_ref style, int fill_mode);
+BSG_EXPORT extern int bsg_draw_style_ref_fill_mode(bsg_draw_style_ref style);
+BSG_EXPORT extern int bsg_draw_style_ref_set_point_size(bsg_draw_style_ref style, double point_size);
+BSG_EXPORT extern double bsg_draw_style_ref_point_size(bsg_draw_style_ref style);
+BSG_EXPORT extern int bsg_draw_style_ref_set_transparency_policy(bsg_draw_style_ref style, int policy);
+BSG_EXPORT extern int bsg_draw_style_ref_transparency_policy(bsg_draw_style_ref style);
+
+__END_DECLS
+
+#endif /* BSG_DRAW_STYLE_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/edit_preview.h

@@ -0,0 +1,83 @@
+/*                  E D I T _ P R E V I E W . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this file; see the file named COPYING for more information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief Typed edit-preview callback contract.
+ */
+/** @{ */
+/* @file bsg/edit_preview.h */
+
+#ifndef BSG_EDIT_PREVIEW_H
+#define BSG_EDIT_PREVIEW_H
+
+#include "common.h"
+#include <stdint.h>
+#include "vmath.h"
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+struct bsg_view;
+
+typedef uint64_t (*bsg_edit_preview_revision_cb_t)(void *preview_ctx);
+typedef int (*bsg_edit_preview_update_cb_t)(void *preview_ctx, struct bsg_view *v);
+typedef int (*bsg_edit_preview_bounds_cb_t)(void *preview_ctx, point_t *bmin, point_t *bmax);
+typedef int (*bsg_edit_preview_pick_cb_t)(void *preview_ctx, struct bsg_view *v, int x, int y, void *pick_out);
+typedef int (*bsg_edit_preview_snap_cb_t)(void *preview_ctx, struct bsg_view *v, const point_t sample_pt, point_t out_pt);
+typedef void (*bsg_edit_preview_free_cb_t)(void *preview_ctx);
+
+typedef enum bsg_edit_preview_stale_reason {
+    BSG_EDIT_PREVIEW_STALE_NONE = 0,
+    BSG_EDIT_PREVIEW_STALE_SOURCE_CHANGED,
+    BSG_EDIT_PREVIEW_STALE_VIEW_INPUT_CHANGED,
+    BSG_EDIT_PREVIEW_STALE_SETTINGS_CHANGED,
+    BSG_EDIT_PREVIEW_STALE_FORCED,
+    BSG_EDIT_PREVIEW_STALE_UPDATE_FAILED
+} bsg_edit_preview_stale_reason;
+
+struct bsg_edit_preview_ops {
+    void *preview_ctx;
+    int owns_preview_ctx;
+    bsg_edit_preview_revision_cb_t revision_cb;
+    bsg_edit_preview_update_cb_t update_cb;
+    bsg_edit_preview_bounds_cb_t bounds_cb;
+    bsg_edit_preview_pick_cb_t pick_cb;
+    bsg_edit_preview_snap_cb_t snap_cb;
+    bsg_edit_preview_free_cb_t free_cb;
+};
+
+#define BSG_EDIT_PREVIEW_OPS_INIT { NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL }
+
+BSG_EXPORT extern const char *
+bsg_edit_preview_stale_reason_name(bsg_edit_preview_stale_reason reason);
+
+__END_DECLS
+
+#endif /* BSG_EDIT_PREVIEW_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/events.h

@@ -0,0 +1,68 @@
+/*                        E V E N T S . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2021-2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * BSG view event constants.
+ *
+ * Canonical home; bv/events.h is a backward-compatibility bridge.
+ */
+/** @{ */
+/* @file bsg/events.h */
+
+#ifndef BSG_EVENTS_H
+#define BSG_EVENTS_H
+
+/** View objects may define their behaviors in response to events (key
+ *  presses, mouse movements, etc.).  Because such events are defined
+ *  on a per-environment basis, we need to define a common language to
+ *  express responses to those events in order to avoid dependence on
+ *  that environment.
+ *
+ *  The calling code is responsible for translating the environment
+ *  specific events into bv events.
+ */
+
+/* BSG-native event constants */
+#define BSG_KEY_PRESS            0x001
+#define BSG_KEY_RELEASE          0x002
+#define BSG_LEFT_MOUSE_PRESS     0x004
+#define BSG_LEFT_MOUSE_RELEASE   0x008
+#define BSG_RIGHT_MOUSE_PRESS    0x010
+#define BSG_RIGHT_MOUSE_RELEASE  0x020
+#define BSG_MIDDLE_MOUSE_PRESS   0x040
+#define BSG_MIDDLE_MOUSE_RELEASE 0x080
+#define BSG_CTRL_MOD             0x100
+#define BSG_SHIFT_MOD            0x200
+#define BSG_ALT_MOD              0x400
+
+
+#endif /* BSG_EVENTS_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * tab-width: 8
+ * mode: C
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/export.h

@@ -0,0 +1,177 @@
+/*                    E X P O R T . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief Semantic export/report records over resolved BSG render batches.
+ *
+ * Export records answer "what is visible/exportable/reportable" without
+ * exposing draw-tree layout.  They are populated from `bsg_render_item`
+ * records and carry source identity, transform, geometry kind, realization
+ * state, appearance, selection, bounds, and LoD state.
+ */
+/** @{ */
+/* @file bsg/export.h */
+
+#ifndef BSG_EXPORT_H
+#define BSG_EXPORT_H
+
+#include "common.h"
+
+#include "vmath.h"
+#include "bu/ptbl.h"
+#include "bu/vls.h"
+#include "bsg/defines.h"
+#include "bsg/render_item.h"
+
+__BEGIN_DECLS
+
+typedef enum bsg_export_record_role {
+    BSG_EXPORT_RECORD_SCENE       = 0x01u,
+    BSG_EXPORT_RECORD_BOUNDS      = 0x04u,
+    BSG_EXPORT_RECORD_LABEL       = 0x08u,
+    BSG_EXPORT_RECORD_ANNOTATION  = 0x10u,
+    BSG_EXPORT_RECORD_DIAGNOSTIC  = 0x20u,
+    BSG_EXPORT_RECORD_GEOMETRY    = 0x40u
+} bsg_export_record_role;
+
+#define BSG_EXPORT_QUERY_VISIBLE_ONLY 0x0001u
+#define BSG_EXPORT_QUERY_DB_OBJECTS   0x0002u
+#define BSG_EXPORT_QUERY_VIEW_OBJECTS 0x0004u
+#define BSG_EXPORT_QUERY_LOCAL_ONLY   0x0008u
+
+#define BSG_EXPORT_DRAW_MODE_ANY      (-1)
+
+struct bsg_export_request {
+    struct bsg_view *view;       /**< @brief target view context */
+    unsigned int query_flags;    /**< @brief BSG_EXPORT_QUERY_* filters */
+    unsigned int render_flags;   /**< @brief BSG_RENDER_FLAG_* overrides */
+    const char *glob;            /**< @brief optional path/name glob */
+    int draw_mode;               /**< @brief draw mode filter, or BSG_EXPORT_DRAW_MODE_ANY */
+};
+
+struct bsg_export_record {
+    struct bu_vls path;
+    struct bsg_render_source source;
+    mat_t model_mat;
+    unsigned int roles;
+    bsg_render_phase phase;
+    struct bsg_render_geometry geometry;
+    bsg_payload_realization_kind realization_kind;
+    bsg_payload_realization_status realization_status;
+    bsg_payload_stale_reason stale_reason;
+    uint64_t geometry_revision;
+    uint64_t payload_revision;
+    uint64_t cache_identity;
+    uint64_t settings_hash;
+    unsigned int request_flags;
+    unsigned int backend_capabilities;
+    unsigned int capability_gaps;
+    int non_database_source;
+    int visible;
+    int selected;
+    int highlighted;
+    int draw_mode;
+    int line_style;
+    int evaluated_region;
+    unsigned char color[3];
+    fastf_t transparency;
+    point_t bounds_center;
+    fastf_t bounds_radius;
+    int has_bounds;
+    int graph_depth;
+    size_t sequence;
+    int lod_level;
+    int lod_level_count;
+    uint64_t lod_identity;
+    uint64_t lod_policy_identity;
+    size_t vlist_structure_count;
+    size_t vlist_command_count;
+    size_t vlist_point_count;
+};
+
+struct bsg_export_result {
+    struct bu_ptbl records;
+};
+
+typedef int (*bsg_export_segment_cb)(const point_t a,
+				     const point_t b,
+				     void *data);
+
+typedef int (*bsg_export_point_cb)(const point_t pt,
+				   void *data);
+
+BSG_EXPORT extern struct bsg_export_result *
+bsg_export_result_create(void);
+
+BSG_EXPORT extern void
+bsg_export_result_free(struct bsg_export_result *result);
+
+BSG_EXPORT extern size_t
+bsg_export_result_count(const struct bsg_export_result *result);
+
+BSG_EXPORT extern const struct bsg_export_record *
+bsg_export_result_get(const struct bsg_export_result *result, size_t idx);
+
+BSG_EXPORT extern void
+bsg_export_request_init(struct bsg_export_request *request,
+			struct bsg_view *view);
+
+BSG_EXPORT extern struct bsg_export_result *
+bsg_export_query(const struct bsg_export_request *request);
+
+BSG_EXPORT extern struct bsg_export_result *
+bsg_export_scene(struct bsg_view *view,
+		 unsigned int flags);
+
+BSG_EXPORT extern void
+bsg_export_result_serialize(const struct bsg_export_result *result,
+			    struct bu_vls *out);
+
+BSG_EXPORT extern void
+bsg_export_record_geometry_report(const struct bsg_export_record *record,
+				  struct bu_vls *out);
+
+BSG_EXPORT extern size_t
+bsg_export_record_foreach_segment(const struct bsg_export_record *record,
+				  bsg_export_segment_cb cb,
+				  void *data);
+
+BSG_EXPORT extern int
+bsg_export_record_has_segments(const struct bsg_export_record *record);
+
+BSG_EXPORT extern size_t
+bsg_export_record_foreach_point(const struct bsg_export_record *record,
+				bsg_export_point_cb cb,
+				void *data);
+
+__END_DECLS
+
+#endif /* BSG_EXPORT_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/faceplate.h

@@ -17,19 +17,21 @@
  * License along with this file; see the file named COPYING for more
  * information.
  */
-/** @addtogroup bv_faceplate
+/** @addtogroup bsg_faceplate
  *
+ * Faceplate / overlay state types.  Canonical home is bsg/faceplate.h;
+ * bv/faceplate.h is a backward-compatibility bridge.
  */
 /** @{ */
-/** @file bv/faceplate.h */
+/** @file bsg/faceplate.h */
 
-#ifndef DM_BV_FACEPLATE_H
-#define DM_BV_FACEPLATE_H
+#ifndef BSG_FACEPLATE_H
+#define BSG_FACEPLATE_H
 
 #include "common.h"
 #include "vmath.h"
 
-struct bv_adc_state {
+struct bsg_adc_state {
     int         draw;
     int         dv_x;
     int         dv_y;
@@ -54,7 +56,7 @@ struct bv_adc_state {
     int         line_width;
 };
 
-struct bv_grid_state {
+struct bsg_grid_state {
     int       rc;
     int       draw;               /* draw grid */
     int       adaptive;           /* adapt to view size */
@@ -67,7 +69,7 @@ struct bv_grid_state {
     int       color[3];
 };
 
-struct bv_interactive_rect_state {
+struct bsg_interactive_rect_state {
     int        active;     /* 1 - actively drawing a rectangle */
     int        draw;       /* draw rubber band rectangle */
     int        line_width;
@@ -85,7 +87,7 @@ struct bv_interactive_rect_state {
 };
 
 
-struct bv_params_state {
+struct bsg_params_state {
     int draw;              /* Overall on/off toggle */
     int draw_size;         /* Print view size */
     int draw_center;       /* Print view X,Y,Z center point */
@@ -98,14 +100,14 @@ struct bv_params_state {
 };
 
 
-struct bv_other_state {
+struct bsg_other_state {
     int gos_draw;
     int gos_line_color[3];
     int gos_text_color[3];
     int gos_font_size;
 };
 
-#endif /* DM_BV_FACEPLATE_H */
+#endif /* BSG_FACEPLATE_H */
 
 /** @} */
 /*

include/bsg/feature.h

@@ -0,0 +1,472 @@
+/*                     F E A T U R E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Typed view features for user-facing, non-database drawing.
+ */
+/** @{ */
+/* @file bsg/feature.h */
+
+#ifndef BSG_FEATURE_H
+#define BSG_FEATURE_H
+
+#include "common.h"
+#include "bu/list.h"
+#include "bu/vls.h"
+#include "vmath.h"
+#include "bsg/defines.h"
+#include "bsg/edit_preview.h"
+#include "bsg/overlay.h"
+#include "bsg/scene_builder.h"
+
+__BEGIN_DECLS
+
+enum bsg_feature_family {
+    BSG_FEATURE_UNKNOWN = 0,
+    BSG_FEATURE_ANNOTATION,
+    BSG_FEATURE_TEXT,
+    BSG_FEATURE_LABEL,
+    BSG_FEATURE_LABEL_LEADER,
+    BSG_FEATURE_AXES,
+    BSG_FEATURE_GRID,
+    BSG_FEATURE_LINES,
+    BSG_FEATURE_ARROW,
+    BSG_FEATURE_POLYGON,
+    BSG_FEATURE_SKETCH,
+    BSG_FEATURE_MEASUREMENT,
+    BSG_FEATURE_SNAP_HINT,
+    BSG_FEATURE_EDIT_HANDLE,
+    BSG_FEATURE_TRANSIENT_PREVIEW,
+    BSG_FEATURE_HUD,
+    BSG_FEATURE_FACEPLATE,
+    BSG_FEATURE_OVERLAY,
+    BSG_FEATURE_FACE_SET
+};
+
+enum bsg_feature_scope {
+    BSG_FEATURE_SCOPE_SHARED = 1,
+    BSG_FEATURE_SCOPE_LOCAL = 2,
+    BSG_FEATURE_SCOPE_ALL = BSG_FEATURE_SCOPE_SHARED | BSG_FEATURE_SCOPE_LOCAL
+};
+
+typedef struct bsg_feature_ref {
+    uintptr_t token;
+    uint64_t revision;
+} bsg_feature_ref;
+
+#define BSG_FEATURE_REF_NULL_INIT {0, 0}
+
+struct bsg_line_layer_builder;
+struct bsg_line_layer;
+
+struct bsg_feature_opts {
+    enum bsg_feature_family family;
+    int local;
+    int arrow;
+    int visible;
+    int color_valid;
+    unsigned char color[3];
+    int line_width;
+    const char *display_name;
+    const char *owner;
+};
+
+#define BSG_FEATURE_OPTS_INIT { BSG_FEATURE_UNKNOWN, 0, 0, -1, 0, {0, 0, 0}, -1, NULL, NULL }
+
+struct bsg_feature_record {
+    bsg_feature_ref ref;
+    enum bsg_feature_family family;
+    enum bsg_feature_scope scope;
+    const char *name;
+    const char *display_name;
+    const char *owner;
+    int visible;
+    unsigned char color[3];
+    int line_width;
+    size_t child_count;
+    size_t geometry_command_count;
+};
+
+struct bsg_feature_style {
+    int visible;
+    int color_valid;
+    unsigned char color[3];
+    int line_width;
+    int line_style;
+    int arrow;
+    fastf_t arrow_tip_length;
+    fastf_t arrow_tip_width;
+};
+
+#define BSG_FEATURE_STYLE_INIT { -1, 0, {0, 0, 0}, -1, -1, -1, -1.0, -1.0 }
+
+struct bsg_feature_line_layer {
+    const char *name;
+    const point_t *points;
+    const int *commands;
+    size_t point_count;
+    struct bsg_feature_style style;
+};
+
+#define BSG_FEATURE_LINE_LAYER_INIT { NULL, NULL, NULL, 0, BSG_FEATURE_STYLE_INIT }
+
+BSG_EXPORT extern struct bsg_line_layer_builder *
+bsg_line_layer_builder_create(void);
+
+BSG_EXPORT extern void
+bsg_line_layer_builder_clear(struct bsg_line_layer_builder *builder);
+
+BSG_EXPORT extern void
+bsg_line_layer_builder_free(struct bsg_line_layer_builder *builder);
+
+BSG_EXPORT extern size_t
+bsg_line_layer_builder_layer_count(const struct bsg_line_layer_builder *builder);
+
+BSG_EXPORT extern size_t
+bsg_line_layer_builder_point_count(const struct bsg_line_layer_builder *builder);
+
+BSG_EXPORT extern const struct bsg_line_layer *
+bsg_line_layer_builder_layer_at(const struct bsg_line_layer_builder *builder,
+				size_t idx);
+
+BSG_EXPORT extern int
+bsg_line_layer_builder_add(struct bsg_line_layer_builder *builder,
+			   int r,
+			   int g,
+			   int b,
+			   const point_t point,
+			   int command);
+
+BSG_EXPORT extern struct bsg_line_layer *
+bsg_line_layer_builder_find(struct bsg_line_layer_builder *builder,
+			    int r,
+			    int g,
+			    int b);
+
+BSG_EXPORT extern int
+bsg_line_layer_add(struct bsg_line_layer *layer,
+		   const point_t point,
+		   int command);
+
+BSG_EXPORT extern int
+bsg_line_layer_color(const struct bsg_line_layer *layer,
+		     unsigned char *r,
+		     unsigned char *g,
+		     unsigned char *b);
+
+BSG_EXPORT extern size_t
+bsg_line_layer_point_count(const struct bsg_line_layer *layer);
+
+BSG_EXPORT extern int
+bsg_line_layer_point_at(const struct bsg_line_layer *layer,
+			size_t idx,
+			point_t point);
+
+BSG_EXPORT extern int
+bsg_line_layer_command_at(const struct bsg_line_layer *layer,
+			  size_t idx,
+			  int *command);
+
+struct bsg_feature_label_data {
+    const char *text;
+    point_t point;
+    int color_valid;
+    unsigned char color[3];
+    int line_flag;
+    point_t target;
+    int anchor;
+    int arrow;
+};
+
+#define BSG_FEATURE_LABEL_DATA_INIT { NULL, VINIT_ZERO, 0, {0, 0, 0}, 0, VINIT_ZERO, BSG_ANCHOR_AUTO, 0 }
+
+typedef int (*bsg_feature_visit_cb)(bsg_feature_ref ref, const struct bsg_feature_record *record, void *data);
+
+BSG_EXPORT extern const char *
+bsg_feature_family_name(enum bsg_feature_family family);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_create(struct bsg_view *v, const char *name, const struct bsg_feature_opts *opts);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_create_axes(struct bsg_view *v, const char *name, int local);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_create_lines(struct bsg_view *v, const char *name, int local);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_create_label(struct bsg_view *v, const char *name, int local);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_create_arrow(struct bsg_view *v, const char *name, int local);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_create_overlay(struct bsg_view *v, const char *name, int local);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_create_polygon(struct bsg_view *v, const char *name, int local);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_create_face_set(struct bsg_view *v, const char *name, int local);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_create_preview(struct bsg_view *v, const char *name, int local);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_find(struct bsg_view *v, const char *name);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_ref_from_scene(bsg_scene_ref ref);
+
+BSG_EXPORT extern bsg_scene_ref
+bsg_feature_ref_as_scene(bsg_feature_ref ref);
+
+BSG_EXPORT extern int
+bsg_feature_remove(struct bsg_view *v, const char *name);
+
+BSG_EXPORT extern size_t
+bsg_feature_remove_all(struct bsg_view *v, int scope_mask);
+
+BSG_EXPORT extern void
+bsg_feature_visit(struct bsg_view *v, int scope_mask, bsg_feature_visit_cb cb, void *data);
+
+BSG_EXPORT extern int
+bsg_feature_record_get(bsg_feature_ref ref, struct bsg_feature_record *record);
+
+BSG_EXPORT extern int
+bsg_feature_ref_is_null(bsg_feature_ref ref);
+
+BSG_EXPORT extern enum bsg_feature_family
+bsg_feature_family(bsg_feature_ref ref);
+
+BSG_EXPORT extern void
+bsg_feature_set_family(bsg_feature_ref ref, enum bsg_feature_family family);
+
+BSG_EXPORT extern int
+bsg_feature_style_get(bsg_feature_ref ref, struct bsg_feature_style *style);
+
+BSG_EXPORT extern int
+bsg_feature_style_apply(bsg_feature_ref ref, const struct bsg_feature_style *style);
+
+BSG_EXPORT extern int
+bsg_feature_style_apply_recursive(bsg_feature_ref ref,
+				  const struct bsg_feature_style *style);
+
+BSG_EXPORT extern void
+bsg_feature_set_color(bsg_feature_ref ref, int r, int g, int b);
+
+BSG_EXPORT extern void
+bsg_feature_set_line_width(bsg_feature_ref ref, int line_width);
+
+BSG_EXPORT extern void
+bsg_feature_set_visible(bsg_feature_ref ref, int visible);
+
+BSG_EXPORT extern int
+bsg_feature_touch(bsg_feature_ref ref);
+
+BSG_EXPORT extern int
+bsg_feature_realize(bsg_feature_ref ref, struct bsg_view *v, int recursive);
+
+BSG_EXPORT extern int
+bsg_feature_edit_preview_attach(bsg_feature_ref ref,
+				void *editor_ctx,
+				void *aux_ctx,
+				const struct bsg_edit_preview_ops *ops);
+
+BSG_EXPORT extern int
+bsg_feature_edit_preview_set_ops(bsg_feature_ref ref,
+				 const struct bsg_edit_preview_ops *ops);
+
+BSG_EXPORT extern int
+bsg_feature_edit_preview_touch(bsg_feature_ref ref);
+
+BSG_EXPORT extern uint64_t
+bsg_feature_edit_preview_revision(bsg_feature_ref ref);
+
+BSG_EXPORT extern void
+bsg_feature_edit_preview_mark_source_revision(bsg_feature_ref ref,
+					      uint64_t source_revision,
+					      bsg_edit_preview_stale_reason reason);
+
+BSG_EXPORT extern void
+bsg_feature_edit_preview_mark_inputs_revision(bsg_feature_ref ref,
+					      uint64_t inputs_revision,
+					      bsg_edit_preview_stale_reason reason);
+
+BSG_EXPORT extern int
+bsg_feature_edit_preview_is_stale(bsg_feature_ref ref);
+
+BSG_EXPORT extern bsg_edit_preview_stale_reason
+bsg_feature_edit_preview_stale_reason(bsg_feature_ref ref);
+
+BSG_EXPORT extern int
+bsg_feature_edit_preview_realize(bsg_feature_ref ref, struct bsg_view *v);
+
+BSG_EXPORT extern int
+bsg_feature_edit_preview_bounds(bsg_feature_ref ref, point_t *bmin, point_t *bmax);
+
+BSG_EXPORT extern int
+bsg_feature_edit_preview_pick(bsg_feature_ref ref, struct bsg_view *v,
+			      int x, int y, void *pick_out);
+
+BSG_EXPORT extern int
+bsg_feature_edit_preview_snap(bsg_feature_ref ref, struct bsg_view *v,
+			      const point_t sample_pt, point_t out_pt);
+
+BSG_EXPORT extern fastf_t
+bsg_feature_view_depth(bsg_feature_ref ref, struct bsg_view *v, int mode);
+
+BSG_EXPORT extern int
+bsg_feature_points_replace(bsg_feature_ref ref,
+			   enum bsg_feature_family family,
+			   const point_t *points,
+			   const int *cmds,
+			   size_t point_count);
+
+BSG_EXPORT extern int
+bsg_feature_points_copy(bsg_feature_ref ref,
+			point_t **points_out,
+			int **cmds_out,
+			size_t *point_count_out);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_replace_lines(struct bsg_view *v,
+			  const char *name,
+			  int local,
+			  const point_t *points,
+			  size_t point_count,
+			  const struct bsg_feature_style *style);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_replace_line_layers(struct bsg_view *v,
+				const char *name,
+				int local,
+				const struct bsg_feature_line_layer *layers,
+				size_t layer_count,
+				const struct bsg_feature_style *style);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_replace_line_layer_builder(struct bsg_view *v,
+				       const char *name,
+				       int local,
+				       const struct bsg_line_layer_builder *builder,
+				       const struct bsg_feature_style *style);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_replace_indexed_face_set(struct bsg_view *v,
+				     const char *name,
+				     int local,
+				     const point_t *points,
+				     size_t point_count,
+				     const vect_t *normals,
+				     size_t normal_count,
+				     const int *indices,
+				     size_t index_count,
+				     const struct bsg_feature_style *style);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_replace_arrow(struct bsg_view *v,
+			  const char *name,
+			  int local,
+			  const point_t *points,
+			  size_t point_count,
+			  const struct bsg_feature_style *style);
+
+BSG_EXPORT extern bsg_feature_ref
+bsg_feature_replace_axes(struct bsg_view *v,
+			 const char *name,
+			 int local,
+			 const point_t *centers,
+			 size_t center_count,
+			 fastf_t half_axes_size,
+			 const struct bsg_feature_style *style);
+
+BSG_EXPORT extern int
+bsg_feature_axes_state_get(bsg_feature_ref ref, struct bsg_axes *axes_out);
+
+BSG_EXPORT extern int
+bsg_feature_axes_state_replace(bsg_feature_ref ref, const struct bsg_axes *axes);
+
+BSG_EXPORT extern int
+bsg_feature_axes_centers_copy(bsg_feature_ref ref,
+			      point_t **centers_out,
+			      size_t *center_count_out);
+
+BSG_EXPORT extern int
+bsg_feature_arrow_tip_set(bsg_feature_ref ref, fastf_t tip_length, fastf_t tip_width);
+
+BSG_EXPORT extern int
+bsg_feature_arrow_tip_get(bsg_feature_ref ref, fastf_t *tip_length, fastf_t *tip_width);
+
+BSG_EXPORT extern int
+bsg_feature_labels_replace(bsg_feature_ref ref,
+			   const struct bsg_feature_label_data *labels,
+			   size_t label_count);
+
+BSG_EXPORT extern size_t
+bsg_feature_label_count(bsg_feature_ref ref);
+
+BSG_EXPORT extern int
+bsg_feature_label_copy(bsg_feature_ref ref,
+		       size_t index,
+		       struct bu_vls *text_out,
+		       point_t point_out,
+		       unsigned char color_out[3]);
+
+BSG_EXPORT extern int
+bsg_feature_label_point_set(bsg_feature_ref ref, size_t index, const point_t point);
+
+BSG_EXPORT extern int
+bsg_feature_labels_color_set(bsg_feature_ref ref, const unsigned char color[3]);
+
+BSG_EXPORT extern void
+bsg_feature_set_view(bsg_feature_ref ref, struct bsg_view *v);
+
+BSG_EXPORT extern int
+bsg_feature_overlay_register_owner(bsg_feature_ref ref,
+				   const void *owner,
+				   bsg_overlay_role role,
+				   bsg_overlay_class overlay_class,
+				   bsg_overlay_lifecycle lifecycle,
+				   bsg_overlay_order ordering,
+				   const char *source_path,
+				   int sort_order);
+
+BSG_EXPORT extern size_t
+bsg_feature_overlay_auto_remove(struct bsg_view *v, const char *source_path);
+
+BSG_EXPORT extern void
+bsg_feature_labels_sync(struct bsg_view *v, struct bsg_data_label_state *gdlsp, const char *name);
+
+__END_DECLS
+
+#endif /* BSG_FEATURE_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/field.h

@@ -0,0 +1,153 @@
+/*                       F I E L D . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Public opaque field API (SoField analogue).
+ *
+ * Field refs are borrowed handles to field storage owned by their node.
+ * They remain valid until the owning node is destroyed or reset.  Field
+ * connections are non-owning links; callers are responsible for ensuring a
+ * connected source field outlives any destination fields connected to it.
+ */
+/** @{ */
+/* @file bsg/field.h */
+
+#ifndef BSG_FIELD_H
+#define BSG_FIELD_H
+
+#include "common.h"
+#include <stdint.h>
+#include <stddef.h>
+#include "vmath.h"
+#include "bsg/node.h"
+#include "bsg/object.h"
+
+__BEGIN_DECLS
+
+typedef struct bsg_field_ref {
+    void *opaque;
+} bsg_field_ref;
+
+#define BSG_FIELD_REF_NULL_INIT { NULL }
+
+typedef enum bsg_field_value_type {
+    BSG_FIELD_VALUE_INVALID = 0,
+    BSG_FIELD_VALUE_BOOL,
+    BSG_FIELD_VALUE_INT,
+    BSG_FIELD_VALUE_UINT64,
+    BSG_FIELD_VALUE_FLOAT,
+    BSG_FIELD_VALUE_DOUBLE,
+    BSG_FIELD_VALUE_ENUM,
+    BSG_FIELD_VALUE_STRING,
+    BSG_FIELD_VALUE_VEC3,
+    BSG_FIELD_VALUE_COLOR3,
+    BSG_FIELD_VALUE_MATRIX,
+    BSG_FIELD_VALUE_BBOX,
+    BSG_FIELD_VALUE_OBJECT,
+    BSG_FIELD_VALUE_NODE,
+    BSG_FIELD_VALUE_MULTI_NODE,
+    BSG_FIELD_VALUE_MULTI_DOUBLE,
+    BSG_FIELD_VALUE_MULTI_POINT,
+    BSG_FIELD_VALUE_MULTI_INT,
+    BSG_FIELD_VALUE_MULTI_COLOR3
+} bsg_field_value_type;
+
+BSG_EXPORT extern bsg_field_ref bsg_field_ref_null(void);
+BSG_EXPORT extern int bsg_field_ref_is_null(bsg_field_ref ref);
+BSG_EXPORT extern int bsg_field_ref_equal(bsg_field_ref a, bsg_field_ref b);
+BSG_EXPORT extern bsg_node_ref bsg_field_owner(bsg_field_ref ref);
+BSG_EXPORT extern const char *bsg_field_name(bsg_field_ref ref);
+BSG_EXPORT extern bsg_field_value_type bsg_field_ref_value_type(bsg_field_ref ref);
+BSG_EXPORT extern uint64_t bsg_field_revision(bsg_field_ref ref);
+BSG_EXPORT extern int bsg_field_touch(bsg_field_ref ref);
+
+BSG_EXPORT extern int bsg_field_connect(bsg_field_ref dst, bsg_field_ref src);
+BSG_EXPORT extern int bsg_field_disconnect(bsg_field_ref dst);
+BSG_EXPORT extern bsg_field_ref bsg_field_connection(bsg_field_ref ref);
+
+BSG_EXPORT extern bsg_field_ref bsg_node_ref_field(bsg_node_ref node, const char *name);
+BSG_EXPORT extern bsg_field_ref bsg_node_ref_name_field(bsg_node_ref node);
+BSG_EXPORT extern bsg_field_ref bsg_node_ref_visibility_field(bsg_node_ref node);
+BSG_EXPORT extern bsg_field_ref bsg_node_ref_color_field(bsg_node_ref node);
+BSG_EXPORT extern bsg_field_ref bsg_node_ref_transform_field(bsg_node_ref node);
+BSG_EXPORT extern bsg_field_ref bsg_node_ref_bounds_field(bsg_node_ref node);
+BSG_EXPORT extern bsg_field_ref bsg_group_ref_children_field(bsg_group_ref group);
+BSG_EXPORT extern bsg_field_ref bsg_switch_ref_which_child_field(bsg_switch_ref sw);
+
+BSG_EXPORT extern int bsg_field_get_bool(bsg_field_ref ref, int *value);
+BSG_EXPORT extern int bsg_field_set_bool(bsg_field_ref ref, int value);
+BSG_EXPORT extern int bsg_field_get_int(bsg_field_ref ref, int *value);
+BSG_EXPORT extern int bsg_field_set_int(bsg_field_ref ref, int value);
+BSG_EXPORT extern int bsg_field_get_uint64(bsg_field_ref ref, uint64_t *value);
+BSG_EXPORT extern int bsg_field_set_uint64(bsg_field_ref ref, uint64_t value);
+BSG_EXPORT extern int bsg_field_get_float(bsg_field_ref ref, float *value);
+BSG_EXPORT extern int bsg_field_set_float(bsg_field_ref ref, float value);
+BSG_EXPORT extern int bsg_field_get_double(bsg_field_ref ref, double *value);
+BSG_EXPORT extern int bsg_field_set_double(bsg_field_ref ref, double value);
+BSG_EXPORT extern int bsg_field_get_enum(bsg_field_ref ref, int *value);
+BSG_EXPORT extern int bsg_field_set_enum(bsg_field_ref ref, int value);
+BSG_EXPORT extern int bsg_field_get_string(bsg_field_ref ref, const char **value);
+BSG_EXPORT extern int bsg_field_set_string(bsg_field_ref ref, const char *value);
+BSG_EXPORT extern int bsg_field_get_vec3(bsg_field_ref ref, vect_t value);
+BSG_EXPORT extern int bsg_field_set_vec3(bsg_field_ref ref, const vect_t value);
+BSG_EXPORT extern int bsg_field_get_color3(bsg_field_ref ref, unsigned char color[3]);
+BSG_EXPORT extern int bsg_field_set_color3(bsg_field_ref ref, const unsigned char color[3]);
+BSG_EXPORT extern int bsg_field_get_matrix(bsg_field_ref ref, mat_t value);
+BSG_EXPORT extern int bsg_field_set_matrix(bsg_field_ref ref, const mat_t value);
+BSG_EXPORT extern int bsg_field_get_bbox(bsg_field_ref ref, point_t bmin, point_t bmax, int *valid);
+BSG_EXPORT extern int bsg_field_set_bbox(bsg_field_ref ref, const point_t bmin, const point_t bmax, int valid);
+BSG_EXPORT extern int bsg_field_get_object(bsg_field_ref ref, bsg_object_ref *value);
+BSG_EXPORT extern int bsg_field_set_object(bsg_field_ref ref, bsg_object_ref value);
+BSG_EXPORT extern int bsg_field_get_node(bsg_field_ref ref, bsg_node_ref *value);
+BSG_EXPORT extern int bsg_field_set_node(bsg_field_ref ref, bsg_node_ref value);
+
+BSG_EXPORT extern size_t bsg_field_multi_count(bsg_field_ref ref);
+BSG_EXPORT extern int bsg_field_multi_clear(bsg_field_ref ref);
+BSG_EXPORT extern int bsg_field_multi_node_at(bsg_field_ref ref, size_t idx, bsg_node_ref *value);
+BSG_EXPORT extern int bsg_field_multi_node_append(bsg_field_ref ref, bsg_node_ref value);
+BSG_EXPORT extern int bsg_field_multi_node_remove(bsg_field_ref ref, bsg_node_ref value);
+BSG_EXPORT extern int bsg_field_multi_double_at(bsg_field_ref ref, size_t idx, double *value);
+BSG_EXPORT extern int bsg_field_multi_double_set(bsg_field_ref ref, size_t idx, double value);
+BSG_EXPORT extern int bsg_field_multi_double_append(bsg_field_ref ref, double value);
+BSG_EXPORT extern int bsg_field_multi_point_at(bsg_field_ref ref, size_t idx, point_t value);
+BSG_EXPORT extern int bsg_field_multi_point_set(bsg_field_ref ref, size_t idx, const point_t value);
+BSG_EXPORT extern int bsg_field_multi_point_append(bsg_field_ref ref, const point_t value);
+BSG_EXPORT extern int bsg_field_multi_int_at(bsg_field_ref ref, size_t idx, int *value);
+BSG_EXPORT extern int bsg_field_multi_int_set(bsg_field_ref ref, size_t idx, int value);
+BSG_EXPORT extern int bsg_field_multi_int_append(bsg_field_ref ref, int value);
+BSG_EXPORT extern int bsg_field_multi_color3_at(bsg_field_ref ref, size_t idx, unsigned char color[3]);
+BSG_EXPORT extern int bsg_field_multi_color3_set(bsg_field_ref ref, size_t idx, const unsigned char color[3]);
+BSG_EXPORT extern int bsg_field_multi_color3_append(bsg_field_ref ref, const unsigned char color[3]);
+
+__END_DECLS
+
+#endif /* BSG_FIELD_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/geometry.h

@@ -0,0 +1,274 @@
+/*                      G E O M E T R Y . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this file; see the file named COPYING for more information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Public typed geometry nodes.
+ *
+ * Geometry node refs are shape refs whose drawable data is expressed as
+ * fields.  Backends may still receive private realization data while the
+ * drawing stack migrates, but public authoring should use these typed refs
+ * and field accessors.
+ */
+/** @{ */
+/* @file bsg/geometry.h */
+
+#ifndef BSG_GEOMETRY_H
+#define BSG_GEOMETRY_H
+
+#include "common.h"
+#include <stddef.h>
+#include <stdint.h>
+#include "vmath.h"
+#include "bsg/field.h"
+#include "bsg/node.h"
+#include "bsg/object.h"
+#include "bsg/annotation.h"
+#include "bsg/scene_builder.h"
+
+__BEGIN_DECLS
+
+typedef enum bsg_geometry_node_kind {
+    BSG_GEOMETRY_NODE_NONE = 0,
+    BSG_GEOMETRY_NODE_LINE_SET,
+    BSG_GEOMETRY_NODE_INDEXED_LINE_SET,
+    BSG_GEOMETRY_NODE_POINT_SET,
+    BSG_GEOMETRY_NODE_INDEXED_FACE_SET,
+    BSG_GEOMETRY_NODE_MESH,
+    BSG_GEOMETRY_NODE_TEXT,
+    BSG_GEOMETRY_NODE_IMAGE,
+    BSG_GEOMETRY_NODE_FRAMEBUFFER,
+    BSG_GEOMETRY_NODE_OVERLAY,
+    BSG_GEOMETRY_NODE_HUD,
+    BSG_GEOMETRY_NODE_ANNOTATION,
+    BSG_GEOMETRY_NODE_CSG_PROXY,
+    BSG_GEOMETRY_NODE_BREP_PROXY,
+    BSG_GEOMETRY_NODE_EDIT_PREVIEW
+} bsg_geometry_node_kind;
+
+typedef enum bsg_geometry_line_command {
+    BSG_GEOMETRY_LINE_MOVE = 0,
+    BSG_GEOMETRY_LINE_DRAW = 1,
+    BSG_GEOMETRY_POINT_DRAW = 12
+} bsg_geometry_line_command;
+
+typedef struct bsg_line_set_ref { bsg_geometry_ref geometry; } bsg_line_set_ref;
+typedef struct bsg_indexed_line_set_ref { bsg_geometry_ref geometry; } bsg_indexed_line_set_ref;
+typedef struct bsg_point_set_ref { bsg_geometry_ref geometry; } bsg_point_set_ref;
+typedef struct bsg_indexed_face_set_ref { bsg_geometry_ref geometry; } bsg_indexed_face_set_ref;
+typedef struct bsg_mesh_ref { bsg_geometry_ref geometry; } bsg_mesh_ref;
+typedef struct bsg_text_ref { bsg_geometry_ref geometry; } bsg_text_ref;
+typedef struct bsg_image_ref { bsg_geometry_ref geometry; } bsg_image_ref;
+typedef struct bsg_framebuffer_ref { bsg_geometry_ref geometry; } bsg_framebuffer_ref;
+typedef struct bsg_overlay_geometry_ref { bsg_geometry_ref geometry; } bsg_overlay_geometry_ref;
+typedef struct bsg_hud_geometry_ref { bsg_geometry_ref geometry; } bsg_hud_geometry_ref;
+typedef struct bsg_annotation_ref { bsg_geometry_ref geometry; } bsg_annotation_ref;
+typedef struct bsg_csg_proxy_ref { bsg_geometry_ref geometry; } bsg_csg_proxy_ref;
+typedef struct bsg_brep_proxy_ref { bsg_geometry_ref geometry; } bsg_brep_proxy_ref;
+typedef struct bsg_edit_preview_ref { bsg_geometry_ref geometry; } bsg_edit_preview_ref;
+
+#define BSG_LINE_SET_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_INDEXED_LINE_SET_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_POINT_SET_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_INDEXED_FACE_SET_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_MESH_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_TEXT_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_IMAGE_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_FRAMEBUFFER_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_OVERLAY_GEOMETRY_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_HUD_GEOMETRY_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_ANNOTATION_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_CSG_PROXY_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_BREP_PROXY_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+#define BSG_EDIT_PREVIEW_REF_NULL_INIT { BSG_GEOMETRY_REF_NULL_INIT }
+
+BSG_EXPORT extern bsg_type_id bsg_line_set_type(void);
+BSG_EXPORT extern bsg_type_id bsg_indexed_line_set_type(void);
+BSG_EXPORT extern bsg_type_id bsg_point_set_type(void);
+BSG_EXPORT extern bsg_type_id bsg_indexed_face_set_type(void);
+BSG_EXPORT extern bsg_type_id bsg_mesh_type(void);
+BSG_EXPORT extern bsg_type_id bsg_text_type(void);
+BSG_EXPORT extern bsg_type_id bsg_image_type(void);
+BSG_EXPORT extern bsg_type_id bsg_framebuffer_type(void);
+BSG_EXPORT extern bsg_type_id bsg_overlay_geometry_type(void);
+BSG_EXPORT extern bsg_type_id bsg_hud_geometry_type(void);
+BSG_EXPORT extern bsg_type_id bsg_annotation_type(void);
+BSG_EXPORT extern bsg_type_id bsg_csg_proxy_type(void);
+BSG_EXPORT extern bsg_type_id bsg_brep_proxy_type(void);
+BSG_EXPORT extern bsg_type_id bsg_edit_preview_type(void);
+
+BSG_EXPORT extern bsg_line_set_ref bsg_line_set_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_indexed_line_set_ref bsg_indexed_line_set_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_point_set_ref bsg_point_set_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_indexed_face_set_ref bsg_indexed_face_set_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_mesh_ref bsg_mesh_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_text_ref bsg_text_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_image_ref bsg_image_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_framebuffer_ref bsg_framebuffer_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_overlay_geometry_ref bsg_overlay_geometry_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_hud_geometry_ref bsg_hud_geometry_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_annotation_ref bsg_annotation_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_csg_proxy_ref bsg_csg_proxy_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_brep_proxy_ref bsg_brep_proxy_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_edit_preview_ref bsg_edit_preview_ref_create(struct bsg_view *v, const char *name);
+
+BSG_EXPORT extern bsg_node_ref bsg_line_set_ref_as_node(bsg_line_set_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_indexed_line_set_ref_as_node(bsg_indexed_line_set_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_point_set_ref_as_node(bsg_point_set_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_indexed_face_set_ref_as_node(bsg_indexed_face_set_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_mesh_ref_as_node(bsg_mesh_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_text_ref_as_node(bsg_text_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_image_ref_as_node(bsg_image_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_framebuffer_ref_as_node(bsg_framebuffer_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_overlay_geometry_ref_as_node(bsg_overlay_geometry_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_hud_geometry_ref_as_node(bsg_hud_geometry_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_annotation_ref_as_node(bsg_annotation_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_csg_proxy_ref_as_node(bsg_csg_proxy_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_brep_proxy_ref_as_node(bsg_brep_proxy_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_edit_preview_ref_as_node(bsg_edit_preview_ref ref);
+
+BSG_EXPORT extern bsg_geometry_ref bsg_line_set_ref_as_geometry(bsg_line_set_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_indexed_line_set_ref_as_geometry(bsg_indexed_line_set_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_point_set_ref_as_geometry(bsg_point_set_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_indexed_face_set_ref_as_geometry(bsg_indexed_face_set_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_mesh_ref_as_geometry(bsg_mesh_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_text_ref_as_geometry(bsg_text_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_image_ref_as_geometry(bsg_image_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_framebuffer_ref_as_geometry(bsg_framebuffer_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_overlay_geometry_ref_as_geometry(bsg_overlay_geometry_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_hud_geometry_ref_as_geometry(bsg_hud_geometry_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_annotation_ref_as_geometry(bsg_annotation_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_csg_proxy_ref_as_geometry(bsg_csg_proxy_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_brep_proxy_ref_as_geometry(bsg_brep_proxy_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_edit_preview_ref_as_geometry(bsg_edit_preview_ref ref);
+
+BSG_EXPORT extern bsg_line_set_ref bsg_node_ref_as_line_set(bsg_node_ref ref);
+BSG_EXPORT extern bsg_indexed_line_set_ref bsg_node_ref_as_indexed_line_set(bsg_node_ref ref);
+BSG_EXPORT extern bsg_point_set_ref bsg_node_ref_as_point_set(bsg_node_ref ref);
+BSG_EXPORT extern bsg_indexed_face_set_ref bsg_node_ref_as_indexed_face_set(bsg_node_ref ref);
+BSG_EXPORT extern bsg_mesh_ref bsg_node_ref_as_mesh(bsg_node_ref ref);
+BSG_EXPORT extern bsg_text_ref bsg_node_ref_as_text(bsg_node_ref ref);
+BSG_EXPORT extern bsg_image_ref bsg_node_ref_as_image(bsg_node_ref ref);
+BSG_EXPORT extern bsg_framebuffer_ref bsg_node_ref_as_framebuffer(bsg_node_ref ref);
+BSG_EXPORT extern bsg_overlay_geometry_ref bsg_node_ref_as_overlay_geometry(bsg_node_ref ref);
+BSG_EXPORT extern bsg_hud_geometry_ref bsg_node_ref_as_hud_geometry(bsg_node_ref ref);
+BSG_EXPORT extern bsg_annotation_ref bsg_node_ref_as_annotation(bsg_node_ref ref);
+BSG_EXPORT extern bsg_csg_proxy_ref bsg_node_ref_as_csg_proxy(bsg_node_ref ref);
+BSG_EXPORT extern bsg_brep_proxy_ref bsg_node_ref_as_brep_proxy(bsg_node_ref ref);
+BSG_EXPORT extern bsg_edit_preview_ref bsg_node_ref_as_edit_preview(bsg_node_ref ref);
+
+BSG_EXPORT extern bsg_geometry_node_kind bsg_geometry_ref_kind(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_scene_ref_as_geometry(bsg_scene_ref ref);
+BSG_EXPORT extern bsg_scene_ref bsg_geometry_ref_as_scene(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_geometry_ref_kind_field(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_geometry_ref_coordinates_field(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_geometry_ref_normals_field(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_geometry_ref_colors_field(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_geometry_ref_indices_field(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_geometry_ref_primitive_sets_field(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_geometry_ref_text_field(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_geometry_ref_image_width_field(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_geometry_ref_image_height_field(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_geometry_ref_image_channels_field(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_field_ref bsg_geometry_ref_revision_field(bsg_geometry_ref ref);
+BSG_EXPORT extern uint64_t bsg_geometry_ref_revision(bsg_geometry_ref ref);
+
+BSG_EXPORT extern int bsg_geometry_ref_clear(bsg_geometry_ref ref);
+BSG_EXPORT extern int bsg_geometry_ref_set_line_set(bsg_geometry_ref ref,
+	const point_t *points, const int *commands, size_t point_count);
+BSG_EXPORT extern int bsg_geometry_ref_set_point_set(bsg_geometry_ref ref,
+	const point_t *points, size_t point_count);
+BSG_EXPORT extern int bsg_line_set_ref_set_points(bsg_line_set_ref ref,
+	const point_t *points, const int *commands, size_t point_count);
+BSG_EXPORT extern size_t bsg_line_set_ref_point_count(bsg_line_set_ref ref);
+BSG_EXPORT extern int bsg_line_set_ref_point_at(bsg_line_set_ref ref, size_t idx, point_t value);
+BSG_EXPORT extern int bsg_line_set_ref_command_at(bsg_line_set_ref ref, size_t idx, int *command);
+BSG_EXPORT extern int bsg_point_set_ref_set_points(bsg_point_set_ref ref,
+	const point_t *points, size_t point_count);
+/*
+ * Indexed line sets use a polyline stream in @p indices: non-negative values
+ * index @p points, and -1 terminates the current line.  A trailing -1 is
+ * optional, every non-empty line must contain at least two vertices, and other
+ * negative or out-of-range indices are rejected.
+ */
+BSG_EXPORT extern int bsg_indexed_line_set_ref_set_geometry(bsg_indexed_line_set_ref ref,
+	const point_t *points, size_t point_count, const int *indices, size_t index_count);
+/*
+ * Indexed face sets use a polygon stream in @p indices: non-negative values
+ * index @p points, and -1 terminates the current face.  A trailing -1 is
+ * optional, every face must contain at least three vertices, and normals are
+ * optional.  When supplied, normals must be per-index-entry, per-vertex, or
+ * per-face.  Per-index-entry normals correspond only to non-negative vertex
+ * index entries; -1 face separators do not have normals.
+ */
+BSG_EXPORT extern int bsg_indexed_face_set_ref_set_geometry(bsg_indexed_face_set_ref ref,
+	const point_t *points, size_t point_count, const int *indices, size_t index_count);
+BSG_EXPORT extern int bsg_geometry_ref_set_indexed_face_set(bsg_geometry_ref ref,
+	const point_t *points, size_t point_count,
+	const vect_t *normals, size_t normal_count,
+	const int *indices, size_t index_count);
+/* Replace indexed face fields while preserving the existing geometry object. */
+BSG_EXPORT extern int bsg_geometry_ref_update_indexed_face_set(bsg_geometry_ref ref,
+	const point_t *points, size_t point_count,
+	const vect_t *normals, size_t normal_count,
+	const int *indices, size_t index_count);
+BSG_EXPORT extern int bsg_mesh_ref_set_lod(bsg_mesh_ref ref,
+	struct bsg_mesh_lod *mesh);
+BSG_EXPORT extern int bsg_text_ref_set_text(bsg_text_ref ref,
+	const char *text, const point_t position, int size);
+BSG_EXPORT extern int bsg_hud_geometry_ref_set_text(bsg_hud_geometry_ref ref,
+	const char *text, fastf_t x, fastf_t y, int size);
+BSG_EXPORT extern int bsg_annotation_ref_set_record(bsg_annotation_ref ref,
+	const char *summary,
+	bsg_annotation_space space,
+	const point_t anchor,
+	const mat_t model_mat,
+	const mat_t display_mat,
+	const point_t *points,
+	size_t point_count,
+	const struct bsg_annotation_segment *segments,
+	size_t segment_count);
+BSG_EXPORT extern int bsg_geometry_ref_set_annotation(bsg_geometry_ref ref,
+	const char *summary,
+	bsg_annotation_space space,
+	const point_t anchor,
+	const mat_t model_mat,
+	const mat_t display_mat,
+	const point_t *points,
+	size_t point_count,
+	const struct bsg_annotation_segment *segments,
+	size_t segment_count);
+BSG_EXPORT extern int bsg_image_ref_set_metadata(bsg_image_ref ref,
+	size_t width, size_t height, size_t channels);
+BSG_EXPORT extern int bsg_framebuffer_ref_set_mode(bsg_framebuffer_ref ref, int mode);
+
+__END_DECLS
+
+#endif /* BSG_GEOMETRY_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/group.h

@@ -0,0 +1,59 @@
+/*                         G R O U P . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Public typed group child-list API.
+ */
+/** @{ */
+/* @file bsg/group.h */
+
+#ifndef BSG_GROUP_H
+#define BSG_GROUP_H
+
+#include "common.h"
+#include "bsg/node.h"
+
+__BEGIN_DECLS
+
+/*
+ * Child-list operations do not transfer ownership.  Appending records a
+ * parent relationship; callers that own child refs remain responsible for
+ * releasing them unless another documented owner takes over.
+ */
+BSG_EXPORT extern size_t bsg_group_ref_child_count(bsg_group_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_group_ref_child_at(bsg_group_ref ref, size_t idx);
+BSG_EXPORT extern void bsg_group_ref_append_child(bsg_group_ref parent, bsg_node_ref child);
+BSG_EXPORT extern void bsg_group_ref_remove_child(bsg_group_ref parent, bsg_node_ref child);
+
+__END_DECLS
+
+#endif /* BSG_GROUP_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/hud.h

@@ -0,0 +1,257 @@
+/*                        H U D . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Per-view HUD root and overlay
+ * role/lifecycle/order metadata.
+ *
+ * A @c bsg_view owns a HUD scene root (@c gv_hud_root) that is separate
+ * from the model scene attachment.  The HUD root contains one
+ * child per faceplate feature (center dot, axes, scale, ADC,
+ * grid, rubber-band rect, params text, framebuffer).  Each feature carries a
+ * @c bsg_hud_node_meta descriptor that records:
+ *
+ *   - which faceplate feature it represents (@c bsg_hud_feature_type)
+ *   - its coordinate space (@c bsg_hud_coord)
+ *   - its render-stack placement (@c bsg_overlay_role)
+ *   - its semantic overlay class (@c bsg_overlay_class)
+ *   - its lifecycle policy (@c bsg_overlay_lifecycle)
+ *   - its render-phase sort order
+ *
+ * @c bsg_hud_sync() reads the canonical faceplate records exposed by
+ * @c bsg/view_state.h and updates each feature node's visibility state
+ * (UP = enabled, DOWN = disabled) plus a lightweight HUD payload snapshot
+ * stored behind HUD accessors.
+ * The HUD render pass then collects @c gv_hud_root through
+ * @c bsg_render_request_collect() using @c sort_order to order the items.
+ *
+ * Actual rasterisation stays in libdm via a backend adapter that consumes the
+ * HUD render items produced by the render batch collector.
+ */
+/** @{ */
+/* @file bsg/hud.h */
+
+#ifndef BSG_HUD_H
+#define BSG_HUD_H
+
+#include "common.h"
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+struct bsg_view;   /* forward declaration */
+
+
+/* -----------------------------------------------------------------------
+ * Overlay role
+ *
+ * Describes where in the render stack a node lives.
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Overlay rendering role — controls when in the render pipeline a node is
+ * drawn relative to scene geometry.
+ */
+typedef enum bsg_overlay_role {
+    BSG_OVERLAY_ROLE_MODEL  = 0, /**< @brief drawn after scene solids, in model space */
+    BSG_OVERLAY_ROLE_SCREEN = 1, /**< @brief drawn after model overlays, in screen/HUD space */
+    BSG_OVERLAY_ROLE_XRAY   = 2  /**< @brief always on top (depth-ignore), in model space */
+} bsg_overlay_role;
+
+/**
+ * Semantic overlay class — records what kind of overlay/HUD feature a node
+ * represents independent of its placement in the render pipeline.
+ */
+typedef enum bsg_overlay_class {
+    BSG_OVERLAY_CLASS_FACEPLATE             = 0, /**< @brief built-in faceplate/HUD feature */
+    BSG_OVERLAY_CLASS_EDIT_HANDLE           = 1, /**< @brief edit handles / grips */
+    BSG_OVERLAY_CLASS_MEASURE               = 2, /**< @brief measurement graphics */
+    BSG_OVERLAY_CLASS_SELECTION_RUBBER_BAND = 3, /**< @brief selection rectangle */
+    BSG_OVERLAY_CLASS_SNAP_GUIDE            = 4, /**< @brief snapping guide */
+    BSG_OVERLAY_CLASS_COMMAND_RESULT        = 5, /**< @brief command-owned result graphic */
+    BSG_OVERLAY_CLASS_DIAGNOSTIC            = 6, /**< @brief diagnostics / status visuals */
+    BSG_OVERLAY_CLASS_TCL_OVERLAY           = 7, /**< @brief Tcl-created overlay */
+    BSG_OVERLAY_CLASS_POLYGON_EDIT          = 8, /**< @brief polygon edit helper */
+    BSG_OVERLAY_CLASS_SKETCH_EDIT           = 9, /**< @brief sketch edit helper */
+    BSG_OVERLAY_CLASS_USER_ANNOTATION       = 10 /**< @brief user-created annotation */
+} bsg_overlay_class;
+
+
+/* -----------------------------------------------------------------------
+ * HUD coordinate space
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Coordinate space used for geometry in a HUD node.
+ */
+typedef enum bsg_hud_coord {
+    BSG_HUD_COORD_SCREEN_PX       = 0, /**< @brief pixel coordinates (0,0 = top-left) */
+    BSG_HUD_COORD_NDC             = 1, /**< @brief normalized device coords (+-1) */
+    BSG_HUD_COORD_VIEW_PLANE      = 2, /**< @brief view-plane coords (same as NDC for ortho) */
+    BSG_HUD_COORD_MODEL_ANCHORED  = 3  /**< @brief label anchored to a model-space point */
+} bsg_hud_coord;
+
+
+/* -----------------------------------------------------------------------
+ * Overlay lifecycle policy
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Lifecycle policy for an overlay or HUD node.
+ */
+typedef enum bsg_overlay_lifecycle {
+    BSG_OVERLAY_LC_PERSISTENT             = 0, /**< @brief node survives across frames; only rebuilt on settings change */
+    BSG_OVERLAY_LC_PER_FRAME              = 1, /**< @brief node is rebuilt/refreshed every frame */
+    BSG_OVERLAY_LC_PER_COMMAND            = 2, /**< @brief node lives for one command result */
+    BSG_OVERLAY_LC_PER_TOOL               = 3, /**< @brief node lives for one tool session */
+    BSG_OVERLAY_LC_PER_VIEW               = 4, /**< @brief node is private to one view */
+    BSG_OVERLAY_LC_SHARED_VIEW_SET        = 5, /**< @brief node is shared by a view set */
+    BSG_OVERLAY_LC_AUTO_REMOVE_ON_SOURCE  = 6  /**< @brief remove when source object changes */
+} bsg_overlay_lifecycle;
+
+
+/* -----------------------------------------------------------------------
+ * Faceplate feature type
+ *
+ * Identifies which faceplate feature a HUD node represents.
+ * Values also serve as the default sort_order (render-phase position).
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Faceplate feature tag stored in @c bsg_hud_node_meta::feature_type.
+ * Numeric values define the default render-phase order: lower values are
+ * drawn first.
+ */
+typedef enum bsg_hud_feature_type {
+    BSG_HUD_FEATURE_CENTER_DOT  = 0, /**< @brief single center dot (screen-space point) */
+    BSG_HUD_FEATURE_MODEL_AXES  = 1, /**< @brief model-space axes widget */
+    BSG_HUD_FEATURE_VIEW_AXES   = 2, /**< @brief view-space axes widget (corner) */
+    BSG_HUD_FEATURE_VIEW_SCALE  = 3, /**< @brief linear scale bar */
+    BSG_HUD_FEATURE_ADC         = 4, /**< @brief angle/distance cursor */
+    BSG_HUD_FEATURE_GRID        = 5, /**< @brief reference grid */
+    BSG_HUD_FEATURE_RECT        = 6, /**< @brief rubber-band selection rectangle */
+    BSG_HUD_FEATURE_VIEW_PARAMS = 7, /**< @brief text overlay (size, center, az/el, FPS) */
+    BSG_HUD_FEATURE_FRAMEBUFFER = 8  /**< @brief framebuffer underlay/overlay */
+} bsg_hud_feature_type;
+
+/** Number of distinct faceplate features managed by the HUD root. */
+#define BSG_HUD_FEATURE_COUNT 9
+
+
+/* -----------------------------------------------------------------------
+ * Per-node HUD metadata
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Metadata attached to each HUD child record.
+ */
+struct bsg_hud_node_meta {
+    bsg_hud_feature_type  feature_type; /**< @brief which faceplate feature */
+    bsg_hud_coord         coord_space;  /**< @brief geometry coordinate convention */
+    bsg_overlay_role      role;         /**< @brief render-pass placement */
+    bsg_overlay_class     overlay_class;/**< @brief semantic overlay classification */
+    bsg_overlay_lifecycle lifecycle;    /**< @brief rebuild frequency */
+    int                   sort_order;   /**< @brief render-phase ordering (lower = earlier) */
+};
+
+/**
+ * HUD payload snapshot stored on each HUD feature record.
+ *
+ * This records the current faceplate/HUD state needed by the libdm HUD
+ * backend adapter without requiring it to reach back into command or UI
+ * state for feature-specific bookkeeping.
+ */
+struct bsg_hud_payload {
+    bsg_hud_feature_type feature_type; /**< @brief feature this payload snapshot represents */
+    union {
+	struct bsg_other_state            other;
+	struct bsg_axes                   axes;
+	struct bsg_adc_state              adc;
+	struct bsg_grid_state             grid;
+	struct bsg_interactive_rect_state rect;
+	struct bsg_params_state           params;
+	struct {
+	    int mode;
+	} framebuffer;
+    } data;
+};
+
+
+/* -----------------------------------------------------------------------
+ * HUD root management
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Create the per-view HUD root for @p v and store it in @p v->gv_hud_root.
+ *
+ * Pre-allocates @c BSG_HUD_FEATURE_COUNT child nodes (one per faceplate
+ * feature), each initially disabled.  @c bsg_hud_sync() subsequently updates
+ * visibility to reflect the current retained faceplate records.
+ *
+ * Returns 0 on success, -1 if @p v is NULL or allocation fails.  If the HUD
+ * root already exists this is a no-op.
+ */
+BSG_EXPORT extern int
+bsg_hud_ensure(struct bsg_view *v);
+
+
+/**
+ * Destroy the HUD root and all its child feature nodes, and clear
+ * @p v->gv_hud_root.
+ *
+ * No-op if @p v is NULL or the HUD root has not been created.
+ */
+BSG_EXPORT extern void
+bsg_hud_root_destroy(struct bsg_view *v);
+
+
+/**
+ * Synchronize the HUD root's child nodes with the current faceplate settings
+ * exposed by @p v's view-state record.
+ *
+ * For each faceplate feature: if enabled, the corresponding child node's
+ * visible when enabled and hidden when disabled.  The HUD root is created
+ * automatically on first call if it does not yet exist.
+ *
+ * Returns 0 on success, -1 if @p v is NULL or the root cannot be created.
+ */
+BSG_EXPORT extern int
+bsg_hud_sync(struct bsg_view *v);
+
+
+/**
+ * HUD node metadata access is private to libbsg render collection.
+ */
+
+__END_DECLS
+
+#endif /* BSG_HUD_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/identity.h

@@ -0,0 +1,47 @@
+/*                     I D E N T I T Y . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Public node identity is exposed through stable feature, draw, render,
+ * backend, and export records.  Raw node identity and revision storage
+ * mutation is private to libbsg.
+ */
+/** @{ */
+/* @file bsg/identity.h */
+
+#ifndef BSG_IDENTITY_H
+#define BSG_IDENTITY_H
+
+#include "common.h"
+#include "bsg/defines.h"
+
+#endif /* BSG_IDENTITY_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/interaction.h

@@ -0,0 +1,188 @@
+/*                 I N T E R A C T I O N . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief Unified interaction records for pick, selection, snap, measure,
+ * highlight, and edit-feature workflows.
+ */
+/** @{ */
+/* @file bsg/interaction.h */
+
+#ifndef BSG_INTERACTION_H
+#define BSG_INTERACTION_H
+
+#include "common.h"
+#include "bu/ptbl.h"
+#include "bu/vls.h"
+#include "vmath.h"
+#include "bsg/defines.h"
+#include "bsg/feature.h"
+#include "bsg/snap_action.h"
+
+__BEGIN_DECLS
+
+struct bsg_measure_result;
+struct bsg_pick_record;
+struct bsg_pick_result;
+struct bsg_selection;
+struct bsg_snap_candidate;
+struct bsg_snap_result;
+
+typedef enum {
+    BSG_INTERACTION_PICK_HIT = 1,
+    BSG_INTERACTION_SELECTED_PATH,
+    BSG_INTERACTION_HIGHLIGHTED_REF,
+    BSG_INTERACTION_SNAP_CANDIDATE,
+    BSG_INTERACTION_MEASURE_CANDIDATE,
+    BSG_INTERACTION_EDIT_HANDLE,
+    BSG_INTERACTION_EDIT_PREVIEW
+} bsg_interaction_kind;
+
+typedef enum {
+    BSG_INTERACTION_APPLY_SET = 0,
+    BSG_INTERACTION_APPLY_ADD = 1,
+    BSG_INTERACTION_APPLY_REMOVE = 2
+} bsg_interaction_apply_op;
+
+typedef enum {
+    BSG_EDIT_PREVIEW_BEGIN = 0,
+    BSG_EDIT_PREVIEW_UPDATE,
+    BSG_EDIT_PREVIEW_COMMIT,
+    BSG_EDIT_PREVIEW_CANCEL,
+    BSG_EDIT_PREVIEW_REPLACE_SOURCE,
+    BSG_EDIT_PREVIEW_DISCARD
+} bsg_edit_preview_op;
+
+struct bsg_interaction_record {
+    bsg_interaction_kind kind;
+    struct bsg_view *view;
+    bsg_feature_ref feature;
+    struct bu_vls source_path;
+    struct bu_vls instance_path;
+    point_t point;
+    point_t point_b;
+    int screen_x;
+    int screen_y;
+    fastf_t distance;
+    fastf_t projection;
+    fastf_t normal_alignment;
+    int primitive_id;
+    int subelement_id;
+    bsg_snap_kind snap_kind;
+    bsg_edit_preview_op preview_op;
+    int valid;
+};
+
+struct bsg_interaction_result {
+    struct bu_ptbl records;
+};
+
+BSG_EXPORT extern struct bsg_interaction_result *
+bsg_interaction_result_create(void);
+
+BSG_EXPORT extern void
+bsg_interaction_result_free(struct bsg_interaction_result *result);
+
+BSG_EXPORT extern size_t
+bsg_interaction_result_count(const struct bsg_interaction_result *result);
+
+BSG_EXPORT extern struct bsg_interaction_record *
+bsg_interaction_result_get(const struct bsg_interaction_result *result, size_t idx);
+
+BSG_EXPORT extern struct bsg_interaction_record *
+bsg_interaction_record_create(bsg_interaction_kind kind);
+
+BSG_EXPORT extern struct bsg_interaction_record *
+bsg_interaction_record_create_ref(struct bsg_view *v,
+				  bsg_interaction_kind kind,
+				  bsg_feature_ref feature,
+				  const char *source_path,
+				  const char *instance_path);
+
+BSG_EXPORT extern struct bsg_interaction_record *
+bsg_interaction_record_clone(const struct bsg_interaction_record *src);
+
+BSG_EXPORT extern void
+bsg_interaction_record_free(struct bsg_interaction_record *record);
+
+BSG_EXPORT extern void
+bsg_interaction_result_append(struct bsg_interaction_result *result,
+			      struct bsg_interaction_record *record);
+
+BSG_EXPORT extern const char *
+bsg_interaction_record_path(const struct bsg_interaction_record *record);
+
+BSG_EXPORT extern int
+bsg_interaction_record_equal(const struct bsg_interaction_record *a,
+			     const struct bsg_interaction_record *b);
+
+BSG_EXPORT extern void
+bsg_interaction_record_serialize(const struct bsg_interaction_record *record,
+				 struct bu_vls *out);
+
+BSG_EXPORT extern void
+bsg_interaction_result_serialize(const struct bsg_interaction_result *result,
+				 struct bu_vls *out);
+
+BSG_EXPORT extern struct bsg_interaction_record *
+bsg_interaction_from_pick_record(const struct bsg_pick_record *pick);
+
+BSG_EXPORT extern struct bsg_interaction_result *
+bsg_interaction_from_pick_result(const struct bsg_pick_result *pick_result);
+
+BSG_EXPORT extern struct bsg_interaction_record *
+bsg_interaction_from_snap_candidate(struct bsg_view *v,
+				    const struct bsg_snap_candidate *candidate);
+
+BSG_EXPORT extern struct bsg_interaction_result *
+bsg_interaction_from_snap_result(struct bsg_view *v,
+				 const struct bsg_snap_result *snap_result);
+
+BSG_EXPORT extern struct bsg_interaction_record *
+bsg_interaction_from_measure_result(struct bsg_view *v,
+				    const point_t a,
+				    const point_t b,
+				    const struct bsg_measure_result *measure);
+
+BSG_EXPORT extern struct bsg_interaction_record *
+bsg_interaction_edit_preview_record(struct bsg_view *v,
+				    bsg_feature_ref feature,
+				    bsg_edit_preview_op op,
+				    const char *source_path);
+
+BSG_EXPORT extern void
+bsg_interaction_selection_apply(struct bsg_selection *selection,
+				const struct bsg_interaction_result *result,
+				bsg_interaction_apply_op op);
+
+__END_DECLS
+
+#endif /* BSG_INTERACTION_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/light.h

@@ -0,0 +1,215 @@
+/*                       L I G H T . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Renderer-neutral light descriptors and light node fields.
+ *
+ * A `bsg_light` represents a single light source with a type
+ * (BSG_LIGHT_AMBIENT, BSG_LIGHT_DIRECTIONAL, BSG_LIGHT_POINT or
+ * BSG_LIGHT_SPOT), geometric parameters (position, direction), and
+ * photometric parameters (diffuse/specular color, intensity,
+ * attenuation, spot cone angle).
+ *
+ * The `struct bsg_light` APIs remain as renderer-neutral descriptors for
+ * view/request code.  New scene-graph authoring should use `bsg_light_ref`
+ * nodes and their public fields so action traversal can carry lighting state.
+ */
+/** @{ */
+/* @file bsg/light.h */
+
+#ifndef BSG_LIGHT_H
+#define BSG_LIGHT_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bsg/defines.h"
+#include "bsg/field.h"
+#include "bsg/node.h"
+
+__BEGIN_DECLS
+
+/** Light type constants */
+#define BSG_LIGHT_AMBIENT     0  /**< @brief global ambient term */
+#define BSG_LIGHT_DIRECTIONAL 1  /**< @brief infinite directional light */
+#define BSG_LIGHT_POINT       2  /**< @brief omnidirectional point light */
+#define BSG_LIGHT_SPOT        3  /**< @brief spot light with cone */
+
+/**
+ * Renderer-neutral light descriptor.
+ *
+ * Allocate with bsg_light_create(); release with bsg_light_destroy().
+ */
+struct bsg_light {
+    int     type;               /**< @brief BSG_LIGHT_* constant */
+    point_t position;           /**< @brief world-space position (POINT / SPOT) */
+    vect_t  direction;          /**< @brief unit direction (DIRECTIONAL / SPOT) */
+    float   diffuse[3];         /**< @brief RGB diffuse color [0..1] */
+    float   specular[3];        /**< @brief RGB specular color [0..1] */
+    float   ambient[3];         /**< @brief RGB ambient color [0..1] (AMBIENT type) */
+    fastf_t intensity;          /**< @brief overall intensity scale */
+    fastf_t attenuation[3];     /**< @brief constant / linear / quadratic (POINT/SPOT) */
+    fastf_t spot_cutoff;        /**< @brief half-angle of spot cone in degrees (SPOT) */
+    fastf_t spot_exponent;      /**< @brief spot falloff exponent (SPOT) */
+    int     active;             /**< @brief non-zero if this light is enabled */
+};
+
+/**
+ * Allocate and initialise a light of @p type with sensible defaults:
+ *  - white diffuse/specular (1,1,1), intensity 1.0
+ *  - attenuation (1, 0, 0) — constant, no falloff
+ *  - spot_cutoff 45 degrees, spot_exponent 1
+ *  - active = 1
+ * Returns NULL on allocation failure.
+ */
+BSG_EXPORT extern struct bsg_light *
+bsg_light_create(int type);
+
+/**
+ * Release a light previously allocated by bsg_light_create().
+ * No-op if @p light is NULL.
+ */
+BSG_EXPORT extern void
+bsg_light_destroy(struct bsg_light *light);
+
+/** Set world-space position (meaningful for POINT and SPOT lights). */
+BSG_EXPORT extern void
+bsg_light_set_position(struct bsg_light *light, const point_t pos);
+
+/** Get world-space position. */
+BSG_EXPORT extern void
+bsg_light_get_position(const struct bsg_light *light, point_t pos);
+
+/** Set unit direction vector (meaningful for DIRECTIONAL and SPOT lights). */
+BSG_EXPORT extern void
+bsg_light_set_direction(struct bsg_light *light, const vect_t dir);
+
+/** Get direction vector. */
+BSG_EXPORT extern void
+bsg_light_get_direction(const struct bsg_light *light, vect_t dir);
+
+/** Set diffuse RGB color components in [0..1]. */
+BSG_EXPORT extern void
+bsg_light_set_diffuse(struct bsg_light *light, float r, float g, float b);
+
+/** Get diffuse RGB color. */
+BSG_EXPORT extern void
+bsg_light_get_diffuse(const struct bsg_light *light,
+		      float *r, float *g, float *b);
+
+/** Set specular RGB color components in [0..1]. */
+BSG_EXPORT extern void
+bsg_light_set_specular(struct bsg_light *light, float r, float g, float b);
+
+/** Get specular RGB color. */
+BSG_EXPORT extern void
+bsg_light_get_specular(const struct bsg_light *light,
+		       float *r, float *g, float *b);
+
+/** Set ambient RGB color components in [0..1] (used for AMBIENT type). */
+BSG_EXPORT extern void
+bsg_light_set_ambient(struct bsg_light *light, float r, float g, float b);
+
+/** Get ambient RGB color. */
+BSG_EXPORT extern void
+bsg_light_get_ambient(const struct bsg_light *light,
+		      float *r, float *g, float *b);
+
+/** Set intensity scale. */
+BSG_EXPORT extern void
+bsg_light_set_intensity(struct bsg_light *light, fastf_t intensity);
+
+/** Get intensity scale. */
+BSG_EXPORT extern fastf_t
+bsg_light_get_intensity(const struct bsg_light *light);
+
+/** Set attenuation coefficients (constant, linear, quadratic). */
+BSG_EXPORT extern void
+bsg_light_set_attenuation(struct bsg_light *light,
+			  fastf_t constant,
+			  fastf_t linear,
+			  fastf_t quadratic);
+
+/** Set spot cone half-angle in degrees (SPOT light). */
+BSG_EXPORT extern void
+bsg_light_set_spot_cutoff(struct bsg_light *light, fastf_t degrees);
+
+/** Get spot cone half-angle in degrees. */
+BSG_EXPORT extern fastf_t
+bsg_light_get_spot_cutoff(const struct bsg_light *light);
+
+/** Enable or disable the light (active != 0 → enabled). */
+BSG_EXPORT extern void
+bsg_light_set_active(struct bsg_light *light, int active);
+
+/** Return non-zero if the light is currently active. */
+BSG_EXPORT extern int
+bsg_light_get_active(const struct bsg_light *light);
+
+/** Return the light type (BSG_LIGHT_* constant). */
+BSG_EXPORT extern int
+bsg_light_get_type(const struct bsg_light *light);
+
+BSG_EXPORT extern bsg_field_ref bsg_light_ref_type_field(bsg_light_ref light);
+BSG_EXPORT extern bsg_field_ref bsg_light_ref_position_field(bsg_light_ref light);
+BSG_EXPORT extern bsg_field_ref bsg_light_ref_direction_field(bsg_light_ref light);
+BSG_EXPORT extern bsg_field_ref bsg_light_ref_diffuse_color_field(bsg_light_ref light);
+BSG_EXPORT extern bsg_field_ref bsg_light_ref_specular_color_field(bsg_light_ref light);
+BSG_EXPORT extern bsg_field_ref bsg_light_ref_ambient_color_field(bsg_light_ref light);
+BSG_EXPORT extern bsg_field_ref bsg_light_ref_intensity_field(bsg_light_ref light);
+BSG_EXPORT extern bsg_field_ref bsg_light_ref_active_field(bsg_light_ref light);
+
+BSG_EXPORT extern int bsg_light_ref_set_type(bsg_light_ref light, int type);
+BSG_EXPORT extern int bsg_light_ref_type(bsg_light_ref light);
+BSG_EXPORT extern int bsg_light_ref_set_position(bsg_light_ref light, const point_t position);
+BSG_EXPORT extern int bsg_light_ref_position(bsg_light_ref light, point_t position);
+BSG_EXPORT extern int bsg_light_ref_set_direction(bsg_light_ref light, const vect_t direction);
+BSG_EXPORT extern int bsg_light_ref_direction(bsg_light_ref light, vect_t direction);
+BSG_EXPORT extern int bsg_light_ref_set_diffuse_color(bsg_light_ref light,
+						      const unsigned char color[3]);
+BSG_EXPORT extern int bsg_light_ref_diffuse_color(bsg_light_ref light,
+						  unsigned char color[3]);
+BSG_EXPORT extern int bsg_light_ref_set_specular_color(bsg_light_ref light,
+						       const unsigned char color[3]);
+BSG_EXPORT extern int bsg_light_ref_specular_color(bsg_light_ref light,
+						   unsigned char color[3]);
+BSG_EXPORT extern int bsg_light_ref_set_ambient_color(bsg_light_ref light,
+						      const unsigned char color[3]);
+BSG_EXPORT extern int bsg_light_ref_ambient_color(bsg_light_ref light,
+						  unsigned char color[3]);
+BSG_EXPORT extern int bsg_light_ref_set_intensity(bsg_light_ref light, double intensity);
+BSG_EXPORT extern double bsg_light_ref_intensity(bsg_light_ref light);
+BSG_EXPORT extern int bsg_light_ref_set_active(bsg_light_ref light, int active);
+BSG_EXPORT extern int bsg_light_ref_active(bsg_light_ref light);
+
+__END_DECLS
+
+#endif /* BSG_LIGHT_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/lod.h

@@ -0,0 +1,250 @@
+/*                          L O D . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Level-of-detail helpers for the BSG scene graph.
+ *
+ * Canonical home; bv/lod.h is a backward-compatibility bridge.
+ */
+/** @{ */
+/* @file bsg/lod.h */
+
+#ifndef BSG_LOD_H
+#define BSG_LOD_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bu/ptbl.h"
+#include "bsg/defines.h"
+#include "bsg/field.h"
+#include "bsg/node.h"
+#include "bsg/scene_builder.h"
+
+__BEGIN_DECLS
+
+/* =========================================================================
+ * Public typed LoD node fields
+ * ========================================================================= */
+
+typedef enum bsg_lod_selection {
+    BSG_LOD_SELECT_AUTO = 0,
+    BSG_LOD_SELECT_FORCE_LEVEL = 1
+} bsg_lod_selection;
+
+BSG_EXPORT extern bsg_field_ref bsg_lod_ref_selection_field(bsg_lod_ref lod);
+BSG_EXPORT extern bsg_field_ref bsg_lod_ref_active_level_field(bsg_lod_ref lod);
+BSG_EXPORT extern bsg_field_ref bsg_lod_ref_ranges_field(bsg_lod_ref lod);
+
+BSG_EXPORT extern int bsg_lod_ref_set_selection(bsg_lod_ref lod, int selection);
+BSG_EXPORT extern int bsg_lod_ref_selection(bsg_lod_ref lod);
+BSG_EXPORT extern int bsg_lod_ref_set_active_level(bsg_lod_ref lod, int level);
+BSG_EXPORT extern int bsg_lod_ref_active_level(bsg_lod_ref lod);
+BSG_EXPORT extern size_t bsg_lod_ref_range_count(bsg_lod_ref lod);
+BSG_EXPORT extern int bsg_lod_ref_range_at(bsg_lod_ref lod, size_t idx, double *range);
+BSG_EXPORT extern int bsg_lod_ref_append_range(bsg_lod_ref lod, double range);
+BSG_EXPORT extern int bsg_lod_ref_clear_ranges(bsg_lod_ref lod);
+
+BSG_EXPORT extern size_t bsg_lod_ref_level_count(bsg_lod_ref lod);
+BSG_EXPORT extern bsg_node_ref bsg_lod_ref_level_at(bsg_lod_ref lod, size_t idx);
+BSG_EXPORT extern void bsg_lod_ref_append_level(bsg_lod_ref lod, bsg_node_ref level);
+BSG_EXPORT extern void bsg_lod_ref_remove_level(bsg_lod_ref lod, bsg_node_ref level);
+
+/* =========================================================================
+ * View bounds and object selection
+ * ========================================================================= */
+
+/* Given a view, construct either an oriented bounding box or a view frustum
+ * extruded to contain scene objects visible in the view.  Conceptually, think
+ * of it as a framebuffer pane pushed through the scene in the direction the
+ * camera is looking.  If the view width and height are not set or there is
+ * some other problem, no volume is computed. This function is intended
+ * primarily to be set as an updating callback for the bsg_view structure. */
+BSG_EXPORT extern void
+bsg_view_bounds(struct bsg_view *v);
+
+/* Given a screen x,y coordinate, construct the set of shape nodes whose AABB
+ * intersects the OBB created by projecting that pixel through the scene. */
+BSG_EXPORT int
+bsg_view_pick_candidates(struct bu_ptbl *sset, struct bsg_view *v, int x, int y);
+
+/* Given a screen x1,y1,x2,y2 rectangle, construct and return the set of shape
+ * nodes whose AABB intersects the OBB created by projecting that rectangle
+ * through the scene. */
+BSG_EXPORT int
+bsg_view_rect_pick_candidates(struct bu_ptbl *sset, struct bsg_view *v, int x1, int y1, int x2, int y2);
+
+/* =========================================================================
+ * Mesh LoD context
+ * ========================================================================= */
+
+/* Storing and reading from a lot of small, individual files doesn't work very
+ * well on some platforms.  We provide a "context" to manage bookkeeping of data
+ * across objects. The details are implementation internal - the application
+ * will simply create a context with a file name and provide it to the various
+ * LoD calls. */
+struct bsg_mesh_lod_context_internal;
+struct bsg_mesh_lod_context {
+    struct bsg_mesh_lod_context_internal *i;
+};
+
+/* Create an LoD context using "name". If data is already present associated
+ * with that name it will be loaded, otherwise a new storage structure will be
+ * initialized.  If creation or loading fails for any reason the return value
+ * NULL. */
+BSG_EXPORT struct bsg_mesh_lod_context *
+bsg_mesh_lod_context_create(const char *name);
+
+/* Free all memory associated with context c.  Note that this call does NOT
+ * remove the on-disk data. */
+BSG_EXPORT void
+bsg_mesh_lod_context_destroy(struct bsg_mesh_lod_context *c);
+
+/* Remove cache data associated with key.  If key == 0, remove ALL cache data
+ * associated with all LoD objects in c.  If key == 0 AND c == NULL, clear all
+ * LoD cache data for all .g databases associated with the current user's cache. */
+BSG_EXPORT void
+bsg_mesh_lod_clear_cache(struct bsg_mesh_lod_context *c, unsigned long long key);
+
+/**
+ * Given a set of points and faces, calculate a lookup key and determine if the
+ * cache has the LoD data for this particular mesh.  If it does not, do the
+ * initial calculations to generate the cached LoD data needed for subsequent
+ * lookups, otherwise just return the calculated key.
+ *
+ * @return the lookup key calculated from the data */
+BSG_EXPORT unsigned long long
+bsg_mesh_lod_cache(struct bsg_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);
+
+/**
+ * Given a name, see if the context has a key associated with that name.
+ * If so return it, else return zero. */
+BSG_EXPORT unsigned long long
+bsg_mesh_lod_key_get(struct bsg_mesh_lod_context *c, const char *name);
+
+/**
+ * Given a name and a key, instruct the context to associate that name with
+ * the key.  Returns 0 if successful, else error. */
+BSG_EXPORT int
+bsg_mesh_lod_key_put(struct bsg_mesh_lod_context *c, const char *name, unsigned long long key);
+
+/**
+ * Set up the bsg_mesh_lod container using cached LoD information associated
+ * with key.  If no cached data has been prepared, a NULL container is returned. */
+BSG_EXPORT struct bsg_mesh_lod *
+bsg_mesh_lod_create(struct bsg_mesh_lod_context *c, unsigned long long key);
+
+/* Clean up the lod container. */
+BSG_EXPORT void
+bsg_mesh_lod_destroy(struct bsg_mesh_lod *l);
+
+/**
+ * Load a mesh LoD container's active arrays directly, without requiring the
+ * container to be attached to a scene node payload.
+ *
+ * bsg_mesh_lod_load_level() selects a specific level.  Passing level == -1
+ * returns the current level without changing active arrays.
+ *
+ * bsg_mesh_lod_load_view_scene_ref() selects a level from the view scale and
+ * optional policy on @p v.  If @p visibility_ref is supplied, it is used only
+ * for the visibility test and logging context; the LoD container remains
+ * caller-owned.
+ */
+BSG_EXPORT int
+bsg_mesh_lod_load_level(struct bsg_mesh_lod *l, int level, int reset);
+
+BSG_EXPORT int
+bsg_mesh_lod_load_view_scene_ref(struct bsg_mesh_lod *l,
+				 bsg_scene_ref visibility_ref,
+				 struct bsg_view *v,
+				 int reset);
+
+BSG_EXPORT void
+bsg_mesh_lod_memshrink_scene_ref(bsg_scene_ref ref);
+
+BSG_EXPORT void
+bsg_mesh_lod_memshrink_node_ref(bsg_node_ref ref);
+
+/**
+ * Given a scene object with mesh LoD data attached as a typed mesh payload
+ * and a bsg_view, load the appropriate level of detail for displaying the
+ * mesh in that view.
+ * Returns the level selected.  If v == NULL, return current level of l.
+ * If there is an error or l == NULL, return -1. */
+BSG_EXPORT int
+bsg_mesh_lod_view_scene_ref(bsg_scene_ref ref, struct bsg_view *v, int reset);
+
+BSG_EXPORT int
+bsg_mesh_lod_view_node_ref(bsg_node_ref ref, struct bsg_view *v, int reset);
+
+/**
+ * Given a scene object with mesh LoD data attached as a typed mesh payload
+ * and a detail level, load the appropriate data.
+ * Returns the level selected.  If level == -1, return current level of l.
+ * If there is an error, return -1. */
+BSG_EXPORT int
+bsg_mesh_lod_level_scene_ref(bsg_scene_ref ref, int level, int reset);
+
+BSG_EXPORT int
+bsg_mesh_lod_level_node_ref(bsg_node_ref ref, int level, int reset);
+
+/* Detach and free a scene object's typed mesh LoD payload. */
+BSG_EXPORT void
+bsg_mesh_lod_free_scene_ref(bsg_scene_ref ref);
+
+BSG_EXPORT void
+bsg_mesh_lod_free_node_ref(bsg_node_ref ref);
+
+/* Set function callbacks for retrieving and freeing high levels of mesh detail */
+BSG_EXPORT void
+bsg_mesh_lod_detail_setup_clbk(struct bsg_mesh_lod *lod, int (*clbk)(struct bsg_mesh_lod *, void *), void *cb_data);
+BSG_EXPORT void
+bsg_mesh_lod_detail_clear_clbk(struct bsg_mesh_lod *lod, int (*clbk)(struct bsg_mesh_lod *, void *));
+BSG_EXPORT void
+bsg_mesh_lod_detail_free_clbk(struct bsg_mesh_lod *lod, int (*clbk)(struct bsg_mesh_lod *, void *));
+
+/* =========================================================================
+ * BSG-native LoD source policy
+ * ========================================================================= */
+
+typedef struct bsg_lod_source_ref {
+    uintptr_t token;
+    uint64_t revision;
+} bsg_lod_source_ref;
+
+#define BSG_LOD_SOURCE_REF_NULL_INIT {0, 0}
+
+BSG_EXPORT extern int
+bsg_lod_source_ref_is_null(bsg_lod_source_ref ref);
+
+__END_DECLS
+
+#endif /* BSG_LOD_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/material.h

@@ -0,0 +1,92 @@
+/*                     M A T E R I A L . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Material node fields and scene material accessors.
+ */
+/** @{ */
+/* @file bsg/material.h */
+
+#ifndef BSG_MATERIAL_H
+#define BSG_MATERIAL_H
+
+#include "common.h"
+#include "bsg/defines.h"
+#include "bsg/field.h"
+#include "bsg/node.h"
+#include "bsg/scene_builder.h"
+
+__BEGIN_DECLS
+
+BSG_EXPORT extern bsg_field_ref bsg_material_ref_diffuse_color_field(bsg_material_ref material);
+BSG_EXPORT extern bsg_field_ref bsg_material_ref_specular_color_field(bsg_material_ref material);
+BSG_EXPORT extern bsg_field_ref bsg_material_ref_emissive_color_field(bsg_material_ref material);
+BSG_EXPORT extern bsg_field_ref bsg_material_ref_alpha_field(bsg_material_ref material);
+BSG_EXPORT extern bsg_field_ref bsg_material_ref_shininess_field(bsg_material_ref material);
+BSG_EXPORT extern bsg_field_ref bsg_material_ref_line_color_field(bsg_material_ref material);
+
+BSG_EXPORT extern int bsg_material_ref_set_diffuse_color(bsg_material_ref material,
+							 const unsigned char color[3]);
+BSG_EXPORT extern int bsg_material_ref_diffuse_color(bsg_material_ref material,
+						     unsigned char color[3]);
+BSG_EXPORT extern int bsg_material_ref_set_specular_color(bsg_material_ref material,
+							  const unsigned char color[3]);
+BSG_EXPORT extern int bsg_material_ref_specular_color(bsg_material_ref material,
+						      unsigned char color[3]);
+BSG_EXPORT extern int bsg_material_ref_set_emissive_color(bsg_material_ref material,
+							  const unsigned char color[3]);
+BSG_EXPORT extern int bsg_material_ref_emissive_color(bsg_material_ref material,
+						      unsigned char color[3]);
+BSG_EXPORT extern int bsg_material_ref_set_alpha(bsg_material_ref material, double alpha);
+BSG_EXPORT extern double bsg_material_ref_alpha(bsg_material_ref material);
+BSG_EXPORT extern int bsg_material_ref_set_shininess(bsg_material_ref material, double shininess);
+BSG_EXPORT extern double bsg_material_ref_shininess(bsg_material_ref material);
+BSG_EXPORT extern int bsg_material_ref_set_line_color(bsg_material_ref material,
+						      const unsigned char color[3]);
+BSG_EXPORT extern int bsg_material_ref_line_color(bsg_material_ref material,
+						  unsigned char color[3]);
+
+BSG_EXPORT extern void
+bsg_scene_material_set_rgb(bsg_scene_ref ref, unsigned char r, unsigned char g, unsigned char b);
+
+BSG_EXPORT extern void
+bsg_scene_material_get_rgb(bsg_scene_ref ref, unsigned char *r, unsigned char *g, unsigned char *b);
+
+BSG_EXPORT extern void
+bsg_scene_material_set_revision(bsg_scene_ref ref, uint32_t revision);
+
+BSG_EXPORT extern uint32_t
+bsg_scene_material_revision(bsg_scene_ref ref);
+
+__END_DECLS
+
+#endif /* BSG_MATERIAL_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/measure.h

@@ -0,0 +1,44 @@
+/*                     M E A S U R E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @file bsg/measure.h */
+
+#ifndef BSG_MEASURE_H
+#define BSG_MEASURE_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+struct bsg_measure_result {
+    fastf_t mr_distance;
+    fastf_t mr_projection;
+    fastf_t mr_normal_alignment;
+    int mr_valid;
+};
+
+BSG_EXPORT extern int
+bsg_measure_candidates(struct bsg_view *v, point_t a, point_t b,
+		       struct bsg_measure_result *out);
+
+__END_DECLS
+
+#endif /* BSG_MEASURE_H */

include/bsg/node.h

@@ -0,0 +1,155 @@
+/*                          N O D E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Public opaque typed node references.
+ *
+ * Node refs are thin typed handles over BSG object refs.  A typed ref is null
+ * when its object member is null.  Constructors return owning refs; release
+ * owning refs with bsg_node_ref_destroy() or the matching typed destroy helper.
+ * View-scene accessors return borrowed refs tied to the view attachment; do
+ * not release borrowed view-scene refs with bsg_node_ref_destroy().
+ *
+ * Hierarchy append APIs store a parent-child relationship but do not transfer
+ * ownership of the child ref.  Destroying a parent detaches independently
+ * owned children instead of destroying them.
+ */
+/** @{ */
+/* @file bsg/node.h */
+
+#ifndef BSG_NODE_H
+#define BSG_NODE_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bsg/defines.h"
+#include "bsg/object.h"
+
+__BEGIN_DECLS
+
+typedef struct bsg_node_ref { bsg_object_ref object; } bsg_node_ref;
+typedef struct bsg_group_ref { bsg_node_ref node; } bsg_group_ref;
+typedef struct bsg_separator_ref { bsg_group_ref group; } bsg_separator_ref;
+typedef struct bsg_switch_ref { bsg_group_ref group; } bsg_switch_ref;
+typedef struct bsg_lod_ref { bsg_node_ref node; } bsg_lod_ref;
+typedef struct bsg_transform_ref { bsg_node_ref node; } bsg_transform_ref;
+typedef struct bsg_material_ref { bsg_node_ref node; } bsg_material_ref;
+typedef struct bsg_draw_style_ref { bsg_node_ref node; } bsg_draw_style_ref;
+typedef struct bsg_complexity_ref { bsg_node_ref node; } bsg_complexity_ref;
+typedef struct bsg_camera_ref { bsg_node_ref node; } bsg_camera_ref;
+typedef struct bsg_light_ref { bsg_node_ref node; } bsg_light_ref;
+typedef struct bsg_shape_ref { bsg_node_ref node; } bsg_shape_ref;
+typedef struct bsg_geometry_ref { bsg_shape_ref shape; } bsg_geometry_ref;
+typedef struct bsg_database_source_ref { bsg_node_ref node; } bsg_database_source_ref;
+
+#define BSG_NODE_REF_NULL_INIT { BSG_OBJECT_REF_NULL_INIT }
+#define BSG_GROUP_REF_NULL_INIT { BSG_NODE_REF_NULL_INIT }
+#define BSG_SEPARATOR_REF_NULL_INIT { BSG_GROUP_REF_NULL_INIT }
+#define BSG_SWITCH_REF_NULL_INIT { BSG_GROUP_REF_NULL_INIT }
+#define BSG_LOD_REF_NULL_INIT { BSG_NODE_REF_NULL_INIT }
+#define BSG_TRANSFORM_REF_NULL_INIT { BSG_NODE_REF_NULL_INIT }
+#define BSG_MATERIAL_REF_NULL_INIT { BSG_NODE_REF_NULL_INIT }
+#define BSG_DRAW_STYLE_REF_NULL_INIT { BSG_NODE_REF_NULL_INIT }
+#define BSG_COMPLEXITY_REF_NULL_INIT { BSG_NODE_REF_NULL_INIT }
+#define BSG_CAMERA_REF_NULL_INIT { BSG_NODE_REF_NULL_INIT }
+#define BSG_LIGHT_REF_NULL_INIT { BSG_NODE_REF_NULL_INIT }
+#define BSG_REF_SHAPE_NULL_INIT { BSG_NODE_REF_NULL_INIT }
+#define BSG_GEOMETRY_REF_NULL_INIT { BSG_REF_SHAPE_NULL_INIT }
+#define BSG_DATABASE_SOURCE_REF_NULL_INIT { BSG_NODE_REF_NULL_INIT }
+
+BSG_EXPORT extern bsg_node_ref bsg_node_ref_null(void);
+BSG_EXPORT extern int bsg_node_ref_is_null(bsg_node_ref ref);
+BSG_EXPORT extern int bsg_node_ref_equal(bsg_node_ref a, bsg_node_ref b);
+BSG_EXPORT extern bsg_object_ref bsg_node_ref_object(bsg_node_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_node_ref_from_object(bsg_object_ref object);
+BSG_EXPORT extern bsg_type_id bsg_node_ref_type(bsg_node_ref ref);
+BSG_EXPORT extern int bsg_node_is_a(bsg_node_ref ref, bsg_type_id type);
+BSG_EXPORT extern void bsg_node_ref_destroy(bsg_node_ref ref);
+
+BSG_EXPORT extern void bsg_node_ref_set_name(bsg_node_ref ref, const char *name);
+BSG_EXPORT extern const char *bsg_node_ref_name(bsg_node_ref ref);
+BSG_EXPORT extern void bsg_node_ref_set_visible(bsg_node_ref ref, int visible);
+BSG_EXPORT extern int bsg_node_ref_visible(bsg_node_ref ref);
+BSG_EXPORT extern void bsg_node_ref_set_color(bsg_node_ref ref, unsigned char r, unsigned char g, unsigned char b);
+BSG_EXPORT extern void bsg_node_ref_color(bsg_node_ref ref, unsigned char *r, unsigned char *g, unsigned char *b);
+BSG_EXPORT extern void bsg_node_ref_set_transform(bsg_node_ref ref, const mat_t mat);
+BSG_EXPORT extern void bsg_node_ref_transform(bsg_node_ref ref, mat_t mat);
+BSG_EXPORT extern void bsg_node_ref_set_bounds(bsg_node_ref ref, const point_t bmin, const point_t bmax, int valid);
+BSG_EXPORT extern int bsg_node_ref_bounds(bsg_node_ref ref, point_t bmin, point_t bmax);
+BSG_EXPORT extern bsg_node_ref bsg_node_ref_parent(bsg_node_ref ref);
+
+BSG_EXPORT extern bsg_group_ref bsg_group_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_separator_ref bsg_separator_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_separator_ref bsg_view_scene_separator_ref(struct bsg_view *v, int create);
+BSG_EXPORT extern bsg_switch_ref bsg_switch_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_lod_ref bsg_lod_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_transform_ref bsg_transform_ref_create(struct bsg_view *v, const mat_t mat, const char *name);
+BSG_EXPORT extern bsg_material_ref bsg_material_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_draw_style_ref bsg_draw_style_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_complexity_ref bsg_complexity_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_camera_ref bsg_camera_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_light_ref bsg_light_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_shape_ref bsg_shape_ref_create(struct bsg_view *v, const char *name);
+BSG_EXPORT extern bsg_geometry_ref bsg_geometry_ref_create(struct bsg_view *v, const char *name);
+
+BSG_EXPORT extern bsg_node_ref bsg_group_ref_as_node(bsg_group_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_separator_ref_as_node(bsg_separator_ref ref);
+BSG_EXPORT extern bsg_group_ref bsg_separator_ref_as_group(bsg_separator_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_switch_ref_as_node(bsg_switch_ref ref);
+BSG_EXPORT extern bsg_group_ref bsg_switch_ref_as_group(bsg_switch_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_lod_ref_as_node(bsg_lod_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_transform_ref_as_node(bsg_transform_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_material_ref_as_node(bsg_material_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_draw_style_ref_as_node(bsg_draw_style_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_complexity_ref_as_node(bsg_complexity_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_camera_ref_as_node(bsg_camera_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_light_ref_as_node(bsg_light_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_shape_ref_as_node(bsg_shape_ref ref);
+BSG_EXPORT extern bsg_shape_ref bsg_geometry_ref_as_shape(bsg_geometry_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_geometry_ref_as_node(bsg_geometry_ref ref);
+
+BSG_EXPORT extern bsg_group_ref bsg_node_ref_as_group(bsg_node_ref ref);
+BSG_EXPORT extern bsg_separator_ref bsg_node_ref_as_separator(bsg_node_ref ref);
+BSG_EXPORT extern bsg_switch_ref bsg_node_ref_as_switch(bsg_node_ref ref);
+BSG_EXPORT extern bsg_lod_ref bsg_node_ref_as_lod(bsg_node_ref ref);
+BSG_EXPORT extern bsg_transform_ref bsg_node_ref_as_transform(bsg_node_ref ref);
+BSG_EXPORT extern bsg_material_ref bsg_node_ref_as_material(bsg_node_ref ref);
+BSG_EXPORT extern bsg_draw_style_ref bsg_node_ref_as_draw_style(bsg_node_ref ref);
+BSG_EXPORT extern bsg_complexity_ref bsg_node_ref_as_complexity(bsg_node_ref ref);
+BSG_EXPORT extern bsg_camera_ref bsg_node_ref_as_camera(bsg_node_ref ref);
+BSG_EXPORT extern bsg_light_ref bsg_node_ref_as_light(bsg_node_ref ref);
+BSG_EXPORT extern bsg_shape_ref bsg_node_ref_as_shape(bsg_node_ref ref);
+BSG_EXPORT extern bsg_geometry_ref bsg_node_ref_as_geometry(bsg_node_ref ref);
+
+__END_DECLS
+
+#endif /* BSG_NODE_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/object.h

@@ -0,0 +1,152 @@
+/*                         O B J E C T . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Opaque BSG object references and runtime type IDs.
+ *
+ * Object references are handles, not owned storage.  A function that creates
+ * an object documents whether the returned reference owns a graph object; an
+ * owning reference is released with bsg_object_destroy().  Destroying a null
+ * reference is a no-op.  There is deliberately no public retain/release
+ * protocol in this API.
+ */
+/** @{ */
+/* @file bsg/object.h */
+
+#ifndef BSG_OBJECT_H
+#define BSG_OBJECT_H
+
+#include "common.h"
+#include <stdint.h>
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+typedef uint32_t bsg_type_id;
+
+#define BSG_TYPE_INVALID ((bsg_type_id)0)
+
+typedef struct bsg_object_ref {
+    void *opaque;
+} bsg_object_ref;
+
+#define BSG_OBJECT_REF_NULL_INIT { NULL }
+
+BSG_EXPORT extern bsg_object_ref
+bsg_object_ref_null(void);
+
+BSG_EXPORT extern int
+bsg_object_ref_is_null(bsg_object_ref object);
+
+BSG_EXPORT extern int
+bsg_object_ref_equal(bsg_object_ref a, bsg_object_ref b);
+
+/**
+ * Register a process-global runtime type name under an existing parent type.
+ *
+ * Registration is deterministic and thread-safe.  Re-registering the same
+ * name with the same parent returns the existing type ID; using the same name
+ * with a different parent fails with BSG_TYPE_INVALID.  Type names are copied
+ * into libbsg-owned storage and remain valid for the life of the process.
+ */
+BSG_EXPORT extern bsg_type_id
+bsg_type_register(const char *name, bsg_type_id parent);
+
+BSG_EXPORT extern const char *
+bsg_type_name(bsg_type_id type);
+
+BSG_EXPORT extern int
+bsg_type_is_a(bsg_type_id type, bsg_type_id base);
+
+BSG_EXPORT extern bsg_type_id
+bsg_object_type(bsg_object_ref object);
+
+BSG_EXPORT extern void
+bsg_object_destroy(bsg_object_ref object);
+
+BSG_EXPORT extern bsg_type_id
+bsg_type_object(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_node_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_group_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_separator_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_switch_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_lod_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_transform_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_material_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_draw_style_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_complexity_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_camera_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_light_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_shape_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_geometry_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_field_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_sensor_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_action_type(void);
+
+BSG_EXPORT extern bsg_type_id
+bsg_view_scope_type(void);
+
+__END_DECLS
+
+#endif /* BSG_OBJECT_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/obol_node.h

@@ -0,0 +1,66 @@
+/*                   O B O L _ N O D E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Forward-compatibility stub for eventual Obol scene-graph integration.
+ *
+ * When Obol is vendored under libbsg the types and magic number defined
+ * here will be used to distinguish native Obol nodes from BRL-CAD
+ * scene elements.  For now this header is a placeholder that keeps
+ * include paths consistent across development phases.
+ */
+/** @{ */
+/* @file bsg/obol_node.h */
+
+#ifndef BSG_OBOL_NODE_H
+#define BSG_OBOL_NODE_H
+
+#include "common.h"
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+/** Magic number reserved for future Obol node structs. */
+#define BSG_OBOL_NODE_MAGIC 0x4F424F4CUL /* "OBOL" */
+
+/**
+ * Placeholder for the future obol_node struct that will be used when
+ * Obol is integrated under libbsg.  The struct is intentionally
+ * empty until that work begins.
+ */
+struct bsg_obol_node_placeholder {
+    uint32_t magic; /**< @brief will hold BSG_OBOL_NODE_MAGIC */
+};
+
+__END_DECLS
+
+#endif /* BSG_OBOL_NODE_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/overlay.h

@@ -0,0 +1,98 @@
+/*                    O V E R L A Y . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Pure-BSG overlay ownership helpers.  Installed callers operate on overlay
+ * ownership/source-path records; node group creation, replacement, metadata
+ * slots, and node queries are private libbsg storage details.
+ */
+/** @{ */
+/* @file bsg/overlay.h */
+
+#ifndef BSG_OVERLAY_H
+#define BSG_OVERLAY_H
+
+#include "common.h"
+#include "bu/ptbl.h"
+#include "bu/vls.h"
+#include "bsg/defines.h"
+#include "bsg/hud.h"
+#include "bsg/scene_builder.h"
+
+__BEGIN_DECLS
+
+struct bsg_view;          /* forward-declare to avoid circular includes */
+
+typedef enum {
+    BSG_OVERLAY_ORDER_MODEL = 0,
+    BSG_OVERLAY_ORDER_SCREEN,
+    BSG_OVERLAY_ORDER_XRAY,
+    BSG_OVERLAY_ORDER_POST_TRANSPARENT
+} bsg_overlay_order;
+
+struct bsg_overlay_info {
+    const void *owner;
+    bsg_overlay_role role;
+    bsg_overlay_class overlay_class;
+    bsg_overlay_lifecycle lifecycle;
+    bsg_overlay_order ordering;
+    int sort_order;
+    struct bu_vls source_path;
+};
+
+
+BSG_EXPORT extern size_t
+bsg_overlay_clear_owned(struct bsg_view *v, const void *owner);
+
+BSG_EXPORT extern int
+bsg_overlay_append_scene(struct bsg_view *v, bsg_scene_ref overlay);
+
+BSG_EXPORT extern bsg_scene_ref
+bsg_overlay_find_scene(struct bsg_view *v, const char *name);
+
+BSG_EXPORT extern void
+bsg_overlay_erase_name(struct bsg_view *v, const char *name);
+
+BSG_EXPORT extern int
+bsg_overlay_register_scene_owner(bsg_scene_ref overlay,
+				 const void *owner,
+				 bsg_overlay_role role,
+				 bsg_overlay_class overlay_class,
+				 bsg_overlay_lifecycle lifecycle,
+				 bsg_overlay_order ordering,
+				 const char *source_path,
+				 int sort_order);
+
+
+__END_DECLS
+
+#endif /* BSG_OVERLAY_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/payload.h

@@ -0,0 +1,165 @@
+/*                     P A Y L O A D . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Public payload metadata used by render, export, and backend handoff records.
+ *
+ * This header deliberately exposes semantic payload kinds and resolved data
+ * record layouts, not the private payload owner handle or mutation API.
+ */
+/** @{ */
+/* @file bsg/payload.h */
+
+#ifndef BSG_PAYLOAD_H
+#define BSG_PAYLOAD_H
+
+#include "common.h"
+#include <stddef.h>
+#include <stdint.h>
+#include "bu/vls.h"
+#include "vmath.h"
+#include "bsg/annotation.h"
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+#define BSG_PAYLOAD_PUBLIC_TYPES_DEFINED 1
+
+struct bsg_grid_state;
+struct bsg_mesh_lod;
+struct fb;
+
+typedef enum bsg_payload_realization_kind {
+    BSG_REALIZE_NONE = 0,
+    BSG_REALIZE_WIREFRAME,
+    BSG_REALIZE_EVALUATED_WIREFRAME,
+    BSG_REALIZE_SHADED_MESH,
+    BSG_REALIZE_ADAPTIVE_WIREFRAME,
+    BSG_REALIZE_LOD_MESH,
+    BSG_REALIZE_BREP_DISPLAY,
+    BSG_REALIZE_POLYGON,
+    BSG_REALIZE_EDIT_PREVIEW
+} bsg_payload_realization_kind;
+
+typedef enum bsg_payload_realization_status {
+    BSG_REALIZE_STATUS_CURRENT = 0,
+    BSG_REALIZE_STATUS_STALE,
+    BSG_REALIZE_STATUS_FAILED
+} bsg_payload_realization_status;
+
+typedef enum bsg_payload_stale_reason {
+    BSG_PAYLOAD_STALE_NONE = 0,
+    BSG_PAYLOAD_STALE_SOURCE_CHANGED,
+    BSG_PAYLOAD_STALE_VIEW_INPUT_CHANGED,
+    BSG_PAYLOAD_STALE_SETTINGS_CHANGED,
+    BSG_PAYLOAD_STALE_FORCED,
+    BSG_PAYLOAD_STALE_UPDATE_FAILED
+} bsg_payload_stale_reason;
+
+struct bsg_payload_realization {
+    bsg_payload_realization_kind kind;
+    bsg_payload_realization_status status;
+    bsg_payload_stale_reason stale_reason;
+    uint64_t source_revision;
+    uint64_t inputs_revision;
+    uint64_t generated_revision;
+    uint64_t realized_source_revision;
+    uint64_t realized_inputs_revision;
+    int has_bounds;
+    point_t bmin;
+    point_t bmax;
+    char failure_reason[128];
+};
+
+struct bsg_payload_line_set {
+    size_t point_cnt;
+    point_t *points;
+    int *cmds;
+};
+
+struct bsg_payload_image {
+    size_t width;
+    size_t height;
+    size_t channels;
+    unsigned char *pixels;
+};
+
+struct bsg_payload_framebuffer {
+    struct fb *fbp;
+    int mode;
+};
+
+struct bsg_payload_annotation {
+    struct bu_vls text;
+    bsg_annotation_space space;
+    point_t anchor;
+    mat_t model_mat;
+    mat_t display_mat;
+    size_t point_cnt;
+    point_t *points;
+    size_t segment_cnt;
+    struct bsg_annotation_segment *segments;
+};
+
+typedef enum {
+    BSG_PL_NONE       = 0,
+    BSG_PL_TEXT,
+    BSG_PL_HUD_TEXT,
+    BSG_PL_LINE_SET,
+    BSG_PL_POLYGON,
+    BSG_PL_MESH,
+    BSG_PL_CSG,
+    BSG_PL_BREP,
+    BSG_PL_IMAGE,
+    BSG_PL_FRAMEBUFFER,
+    BSG_PL_AXES,
+    BSG_PL_GRID,
+    BSG_PL_SKETCH,
+    BSG_PL_ANNOTATION,
+    BSG_PL_EDIT_PREVIEW
+} bsg_payload_type;
+
+BSG_EXPORT extern bsg_payload_realization_kind
+bsg_payload_default_realization_kind(bsg_payload_type type);
+
+BSG_EXPORT extern const char *
+bsg_payload_realization_kind_name(bsg_payload_realization_kind kind);
+
+BSG_EXPORT extern const char *
+bsg_payload_realization_status_name(bsg_payload_realization_status status);
+
+BSG_EXPORT extern const char *
+bsg_payload_stale_reason_name(bsg_payload_stale_reason reason);
+
+__END_DECLS
+
+#endif /* BSG_PAYLOAD_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/pick.h

@@ -0,0 +1,273 @@
+/*                         P I C K . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Typed pick records and pick actions.
+ *
+ * A @c bsg_pick_record is the typed result of a scene pick operation.  It
+ * feeds interaction records and selection state without exposing legacy raw
+ * node-table conversion APIs.
+ *
+ * Pick records carry:
+ *  - the matched scene node while the source scene is live;
+ *  - the source-path string from the node's draw intent (when present);
+ *  - the model-space hit distance (for the nearest-hit ordering);
+ *  - the screen coordinates where the pick was initiated;
+ *  - the view the pick was performed against.
+ *
+ * Pick actions build a @c bsg_pick_result (an ordered list of records) from
+ * a view and screen coordinates.  The caller is responsible for freeing the
+ * result with @c bsg_pick_result_free().
+ *
+ * This header is intentionally free of Qt and GED dependencies so that
+ * libbsg can implement the pick logic and Qt/GED consumers can both use it.
+ *
+ * Per the pick and selection API criteria:
+ *   - Tools receive typed records rather than raw node tables.
+ *   - Selection state is stored in bsg_selection; highlighting is derived
+ *     appearance.
+ */
+/** @{ */
+/* @file bsg/pick.h */
+
+#ifndef BSG_PICK_H
+#define BSG_PICK_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bu/ptbl.h"
+#include "bu/vls.h"
+#include "bsg/defines.h"
+#include "bsg/feature.h"
+#include "bsg/scene_builder.h"
+#include "bsg/selection.h"
+
+__BEGIN_DECLS
+
+/* -----------------------------------------------------------------------
+ * Pick operation kind
+ * ----------------------------------------------------------------------- */
+
+/**
+ * What to do with nodes matched by a pick operation.
+ */
+typedef enum {
+    BSG_PICK_OP_SET    = 0,  /**< replace current selection with pick result */
+    BSG_PICK_OP_ADD    = 1,  /**< add pick result to current selection */
+    BSG_PICK_OP_REMOVE = 2   /**< remove pick result from current selection */
+} bsg_pick_op;
+
+/**
+ * Flags controlling D3 pick-action queries.
+ */
+typedef enum {
+    BSG_PICK_INCLUDE_SCENE    = 0x01, /**< include database-drawn scene groups */
+    BSG_PICK_INCLUDE_OVERLAYS = 0x02, /**< include overlay groups/controls      */
+    BSG_PICK_FIRST_ONLY       = 0x04  /**< return nearest hit only              */
+} bsg_pick_flags;
+
+/* -----------------------------------------------------------------------
+ * bsg_pick_record — single pick hit
+ * ----------------------------------------------------------------------- */
+
+/**
+ * One record in a pick result set.
+ *
+ * Lifecycle: allocated and owned by a @c bsg_pick_result; do not free
+ * individual records directly.  Use @c bsg_pick_result_free() to release
+ * the entire result.
+ *
+ * Fields:
+ *   pr_scene        — transient matched scene ref while the source scene is
+ *                     live.  Public consumers should prefer
+ *                     pr_feature/pr_source_path/pr_instance_path for identity.
+ *   pr_feature      — feature ref when the hit source is a feature.
+ *   pr_valid        — non-zero when the semantic identity fields describe a
+ *                     current hit; zero when stale/erased.
+ *   pr_source_path  — source path string copied from the node's draw intent,
+ *                     or empty string when no draw intent is attached.
+ *   pr_hit_dist     — model-space distance from the pick ray origin to the
+ *                     centre of the node's bounding box.  Used for
+ *                     nearest-first ordering.  Negative means not computed.
+ *   pr_primitive_id — primitive identifier when available, else -1.
+ *   pr_subelement_id — subelement identifier when available, else -1.
+ *   pr_instance_path — resolved instance-path string for semantic picks.
+ *   pr_screen_x,
+ *   pr_screen_y     — screen-pixel coordinates where the pick was initiated.
+ *   pr_view         — view the pick was performed against (borrowed).
+ */
+struct bsg_pick_record {
+    bsg_scene_ref      pr_scene;        /**< @brief matched scene ref */
+    bsg_feature_ref    pr_feature;      /**< @brief feature ref, when applicable */
+    int                pr_valid;        /**< @brief semantic hit is valid/current */
+    struct bu_vls      pr_source_path;  /**< @brief drawn source path */
+    fastf_t            pr_hit_dist;     /**< @brief bbox centre hit distance */
+    int                pr_primitive_id; /**< @brief primitive id or -1 */
+    int                pr_subelement_id;/**< @brief subelement id or -1 */
+    struct bu_vls      pr_instance_path;/**< @brief resolved instance path */
+    int                pr_screen_x;     /**< @brief screen X at pick time */
+    int                pr_screen_y;     /**< @brief screen Y at pick time */
+    struct bsg_view   *pr_view;         /**< @brief view (borrowed) */
+};
+
+/* -----------------------------------------------------------------------
+ * bsg_pick_result — ordered list of pick records
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Result of a pick action: a bu_ptbl of @c bsg_pick_record* ordered by
+ * ascending @c pr_hit_dist (nearest first).
+ *
+ * Allocate with a pick action such as @c bsg_pick_point() and release with
+ * @c bsg_pick_result_free().
+ */
+struct bsg_pick_result {
+    struct bu_ptbl  pr_records;  /**< @brief bu_ptbl of bsg_pick_record* */
+};
+
+/* -----------------------------------------------------------------------
+ * Lifecycle
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Allocate an empty pick result.
+ * Returns NULL on allocation failure.
+ */
+BSG_EXPORT extern struct bsg_pick_result *
+bsg_pick_result_create(void);
+
+/**
+ * Free @p res and all pick records it owns.
+ * The referenced nodes and views are NOT freed.
+ * No-op if @p res is NULL.
+ */
+BSG_EXPORT extern void
+bsg_pick_result_free(struct bsg_pick_result *res);
+
+/**
+ * Return the number of pick records in @p res.
+ * Returns 0 if @p res is NULL.
+ */
+BSG_EXPORT extern size_t
+bsg_pick_result_count(const struct bsg_pick_result *res);
+
+/**
+ * Return the @p i-th pick record in @p res, or NULL if @p i is out of range
+ * or @p res is NULL.  Records are ordered nearest-first after any pick action
+ * that computes @c pr_hit_dist.
+ */
+BSG_EXPORT extern struct bsg_pick_record *
+bsg_pick_result_get(const struct bsg_pick_result *res, size_t i);
+
+/* -----------------------------------------------------------------------
+ * Pick actions
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Point pick: find all scene nodes whose bounding boxes are intersected by
+ * the viewing ray through screen pixel (@p x, @p y) in view @p v.
+ *
+ * The result is sorted nearest-first by @c pr_hit_dist.
+ *
+ * When @p first_only is non-zero only the nearest (smallest @c pr_hit_dist)
+ * record is included in the result.
+ *
+ * Returns a newly allocated @c bsg_pick_result on success, or NULL on
+ * allocation failure.  The caller must call @c bsg_pick_result_free().
+ */
+BSG_EXPORT extern struct bsg_pick_result *
+bsg_pick_point(struct bsg_view *v, int x, int y, int first_only);
+
+/**
+ * Rectangle pick: find all scene nodes whose bounding boxes overlap the
+ * screen rectangle [@p x0,@p y0]–[@p x1,@p y1] in view @p v.
+ *
+ * Records in the result are sorted nearest-first by @c pr_hit_dist (bbox
+ * centre distance from view origin).
+ *
+ * Returns a newly allocated @c bsg_pick_result, or NULL on failure.
+ * The caller must call @c bsg_pick_result_free().
+ */
+BSG_EXPORT extern struct bsg_pick_result *
+bsg_pick_rect(struct bsg_view *v,
+	      int x0, int y0, int x1, int y1);
+
+/**
+ * Nearest-only pick: call @c bsg_pick_point() and retain only the record
+ * with the smallest @c pr_hit_dist.
+ *
+ * Returns a newly allocated @c bsg_pick_result with at most one record, or
+ * NULL on failure.  The caller must call @c bsg_pick_result_free().
+ */
+BSG_EXPORT extern struct bsg_pick_result *
+bsg_pick_nearest(struct bsg_view *v, int x, int y);
+
+/**
+ * D3 ray pick: intersect a model-space ray against visible scene and overlay
+ * groups and return sorted typed pick records.
+ */
+BSG_EXPORT extern struct bsg_pick_result *
+bsg_pick_ray(struct bsg_view *v, const point_t orig, const vect_t dir,
+	     bsg_pick_flags flags);
+
+/**
+ * D3 overlay-control pick: return nearest overlay handle/manipulator hit
+ * near screen location (@p x,@p y).  @p role_mask is reserved for overlay
+ * role filtering in later D4 policy work.
+ */
+BSG_EXPORT extern struct bsg_pick_result *
+bsg_pick_nearest_overlay_control(struct bsg_view *v, int x, int y,
+				 unsigned long long role_mask);
+
+/**
+ * D3 semantic-path pick: match draw-intent source paths using glob pattern
+ * semantics and return typed pick records for matching groups.
+ */
+BSG_EXPORT extern struct bsg_pick_result *
+bsg_pick_semantic_path(struct bsg_view *v, const char *path_pattern);
+
+/**
+ * Apply @p res to @p sel according to @p op:
+ *   BSG_PICK_OP_SET    — clear @p sel then add all nodes from @p res.
+ *   BSG_PICK_OP_ADD    — add all nodes from @p res to @p sel.
+ *   BSG_PICK_OP_REMOVE — remove all nodes in @p res from @p sel.
+ *
+ * No-op if @p sel or @p res is NULL.
+ */
+BSG_EXPORT extern void
+bsg_pick_apply(struct bsg_selection    *sel,
+	       struct bsg_pick_result  *res,
+	       bsg_pick_op              op);
+
+__END_DECLS
+
+#endif /* BSG_PICK_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/plot3.h

@@ -17,7 +17,7 @@
  * License along with this file; see the file named COPYING for more
  * information.
  */
-/** @addtogroup bv_plot
+/** @addtogroup bsg_plot
  *
  * @brief A public-domain UNIX plot library, for 2-D and 3-D plotting in 16-bit
  * VAX signed integer spaces, or 64-bit IEEE floating point.
@@ -93,8 +93,8 @@
 /** @{ */
 /** @file plot3.h */
 
-#ifndef PLOT3_H
-#define PLOT3_H
+#ifndef BSG_PLOT3_H
+#define BSG_PLOT3_H
 
 #include "common.h"
 
@@ -3159,7 +3159,7 @@ plot3_invalid(FILE *fp, int mode)
 
 #endif // PLOT3_IMPLEMENTATION
 
-#endif /* PLOT3_H */
+#endif /* BSG_PLOT3_H */
 
 /** @} */
 /*

include/bsg/polygon.h

@@ -0,0 +1,216 @@
+/*                        P O L Y G O N . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2004-2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+
+/*----------------------------------------------------------------------*/
+/** @addtogroup bsg_polygon
+ *
+ *  @brief Functions for working with polygons.
+ *
+ *  Canonical home; bv/polygon.h is a backward-compatibility bridge.
+ */
+/* @file bsg/polygon.h */
+/** @{ */
+
+#ifndef BSG_POLYGON_H
+#define BSG_POLYGON_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bu/color.h"
+#include "bsg/defines.h"
+#include "bsg/feature.h"
+#include "bg/polygon.h"
+#include "bg/polygon_types.h"
+
+__BEGIN_DECLS
+
+/* View polygon logic and types */
+
+#define BSG_POLYGON_GENERAL   0
+#define BSG_POLYGON_CIRCLE    1
+#define BSG_POLYGON_ELLIPSE   2
+#define BSG_POLYGON_RECTANGLE 3
+#define BSG_POLYGON_SQUARE    4
+
+struct bsg_polygon {
+    int                 type;
+    int                 fill_flag;         /* set to shade the interior */
+    vect2d_t            fill_dir;
+    fastf_t             fill_delta;
+    struct bu_color     fill_color;
+    long                curr_contour_i;
+    long                curr_point_i;
+    point_t             origin_point;      /* For non-general polygons  */
+
+    /* We stash the view plane creation, so we know how to return
+     * to it for future 2D alterations */
+    plane_t             vp;
+
+    /* Offset of polygon plane from the view plane.  Allows for moving
+     * the polygon "towards" and "away from" the viewer. */
+    fastf_t vZ;
+
+    /* Actual polygon info */
+    struct bg_polygon polygon;
+
+    /* Arbitrary data */
+    void *u_data;
+};
+
+typedef bsg_feature_ref bsg_polygon_ref;
+
+#define BSG_POLYGON_REF_NULL_INIT BSG_FEATURE_REF_NULL_INIT
+
+struct bsg_polygon_record {
+    bsg_polygon_ref ref;
+    const char *name;
+    int type;
+    int fill_flag;
+    vect2d_t fill_dir;
+    fastf_t fill_delta;
+    struct bu_color fill_color;
+    unsigned char edge_color[3];
+    long curr_contour_i;
+    long curr_point_i;
+    int first_contour_open;
+    size_t contour_count;
+    size_t point_count;
+    point_t origin_point;
+    plane_t vp;
+    fastf_t vZ;
+    void *user_data;
+};
+
+typedef int (*bsg_polygon_record_visit_cb)(bsg_polygon_ref ref, const struct bsg_polygon_record *record, void *data);
+
+BSG_EXPORT extern int bsg_polygon_ref_is_null(bsg_polygon_ref ref);
+
+BSG_EXPORT extern int bsg_polygon_record_get(bsg_polygon_ref ref, struct bsg_polygon_record *record);
+
+BSG_EXPORT extern const struct bsg_polygon *bsg_polygon_data(bsg_polygon_ref ref);
+
+/* Creates a view-owned polygon feature with explicit name and scope. */
+BSG_EXPORT extern bsg_polygon_ref
+bsg_create_polygon_ref(struct bsg_view *v, const char *name, int local, int type, point_t *fp);
+
+/* Creates a view-owned polygon feature by copying existing polygon data. */
+BSG_EXPORT extern bsg_polygon_ref
+bsg_polygon_ref_create_from_data(struct bsg_view *v, const char *name, int local, const struct bsg_polygon *data);
+
+/* Creates a view-owned polygon feature with a default polygon. */
+BSG_EXPORT extern bsg_polygon_ref bsg_create_view_polygon_ref(struct bsg_view *v, int type, point_t *fp);
+
+/* Various update modes have similar logic - we pass in the flags to the update
+ * routine to enable/disable specific portions of the overall flow. */
+#define BSG_POLYGON_UPDATE_DEFAULT         0
+#define BSG_POLYGON_UPDATE_PROPS_ONLY      1
+#define BSG_POLYGON_UPDATE_PT_SELECT       2
+#define BSG_POLYGON_UPDATE_PT_SELECT_CLEAR 3
+#define BSG_POLYGON_UPDATE_PT_MOVE         4
+#define BSG_POLYGON_UPDATE_PT_APPEND       5
+BSG_EXPORT extern int bsg_polygon_update(bsg_polygon_ref ref, struct bsg_view *v, int utype);
+
+BSG_EXPORT extern int bsg_polygon_update_screen_pt(bsg_polygon_ref ref, struct bsg_view *v, int x, int y, int utype);
+
+BSG_EXPORT extern bsg_polygon_ref bsg_view_select_polygon_ref(struct bsg_view *v, point_t *cp);
+
+BSG_EXPORT extern bsg_polygon_ref bsg_view_polygon_find_ref(struct bsg_view *v, const char *name);
+
+BSG_EXPORT extern bsg_polygon_ref bsg_view_polygon_find_scoped_ref(struct bsg_view *v, const char *name, int local_only);
+
+BSG_EXPORT extern bsg_polygon_ref bsg_view_polygon_dup_ref(struct bsg_view *v, const char *name, const char *new_name);
+
+BSG_EXPORT extern void bsg_view_polygon_visit_records(struct bsg_view *v, bsg_polygon_record_visit_cb cb, void *data);
+
+BSG_EXPORT extern size_t bsg_view_polygon_snap_count(struct bsg_view *v, bsg_polygon_ref exclude);
+
+/* Clear selected polygon points on every visible polygon. */
+BSG_EXPORT extern int bsg_view_polygon_clear_point_selection(struct bsg_view *v);
+
+BSG_EXPORT extern int bsg_polygon_move(bsg_polygon_ref ref, point_t *cp, point_t *pp);
+
+BSG_EXPORT extern int bsg_polygon_set_current(bsg_polygon_ref ref, long contour_i, long point_i);
+
+BSG_EXPORT extern int bsg_polygon_set_name(bsg_polygon_ref ref, const char *name);
+
+BSG_EXPORT extern int bsg_polygon_set_view(bsg_polygon_ref ref, struct bsg_view *v);
+
+BSG_EXPORT extern int bsg_polygon_set_visual(bsg_polygon_ref ref,
+					     const struct bu_color *edge_color,
+					     const struct bu_color *fill_color,
+					     fastf_t fill_slope_x,
+					     fastf_t fill_slope_y,
+					     fastf_t fill_density,
+					     fastf_t vZ,
+					     int fill_flag);
+
+BSG_EXPORT extern int bsg_polygon_set_open(bsg_polygon_ref ref, int open);
+
+BSG_EXPORT extern int bsg_polygon_set_contour_open(bsg_polygon_ref ref, long contour_i, int open);
+
+BSG_EXPORT extern int bsg_polygon_set_all_contours_open(bsg_polygon_ref ref, int open);
+
+BSG_EXPORT extern int bsg_polygon_close(bsg_polygon_ref ref);
+
+BSG_EXPORT extern int bsg_polygon_clear_selected_point(bsg_polygon_ref ref);
+
+BSG_EXPORT extern int bsg_polygon_set_fill(bsg_polygon_ref ref, int fill_flag, fastf_t fill_slope_x, fastf_t fill_slope_y, fastf_t fill_density);
+
+BSG_EXPORT extern int bsg_polygon_fill_color_get(bsg_polygon_ref ref, struct bu_color *fill_color);
+
+BSG_EXPORT extern int bsg_polygon_fill_color_set(bsg_polygon_ref ref, const struct bu_color *fill_color);
+
+BSG_EXPORT extern int bsg_polygon_remove(bsg_polygon_ref ref);
+
+BSG_EXPORT extern void *bsg_polygon_user_data(bsg_polygon_ref ref);
+
+BSG_EXPORT extern int bsg_polygon_user_data_set(bsg_polygon_ref ref, void *user_data);
+
+/* Copy a bv polygon.  Note that this also performs a
+ * view sync - if the user is copying the polygon into
+ * another view, they will have to update the output's
+ * bsg_view to match their target view. */
+BSG_EXPORT extern void bsg_polygon_cpy(struct bsg_polygon *dest, const struct bsg_polygon *src);
+
+/* Calculate a suggested default fill delta based on the polygon structure.  The
+ * idea is to try and strike a balance between line count and having enough fill
+ * lines to highlight interior holes. */
+BSG_EXPORT extern int bsg_polygon_calc_fdelta(struct bsg_polygon *p);
+
+BSG_EXPORT extern struct bg_polygon *
+bsg_polygon_fill_segments(struct bg_polygon *poly, plane_t *vp, vect2d_t line_slope, fastf_t line_spacing);
+
+/* For all polygon bsg_scene_objs in the objs table, apply the specified boolean
+ * op using p and replace the original polygon geometry in objs with the results. */
+BSG_EXPORT extern int bsg_polygon_csg_ref(bsg_polygon_ref target, bsg_polygon_ref stencil, bg_clip_t op);
+
+__END_DECLS
+
+#endif  /* BSG_POLYGON_H */
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/render.h

@@ -0,0 +1,227 @@
+/*                      R E N D E R . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * BSG render-request — retained render-item collection and dispatch.
+ *
+ * A `bsg_render_request` bundles together:
+ *   - a target view (bsg_view*)
+ *   - a retained scene stream selected from the view and request flags
+ *   - a display-manager handle (void*) forwarded to payload realization
+ *   - a set of BSG_RENDER_FLAG_* control flags
+ *
+ * bsg_render_request_collect() resolves the retained stream into a
+ * bsg_render_batch: an immutable, phase-ordered sequence of bsg_render_item
+ * records.  Backends consume that batch with bsg_render_batch_dispatch().
+ * bsg_render_request_execute() is a compatibility wrapper over those two
+ * operations.
+ */
+/** @{ */
+/* @file bsg/render.h */
+
+#ifndef BSG_RENDER_H
+#define BSG_RENDER_H
+
+#include "common.h"
+#include "bu/ptbl.h"
+#include "bsg/defines.h"
+#include "bsg/render_item.h"
+#include "bsg/backend_adapter.h"
+#include "bsg/render_settings.h"
+
+__BEGIN_DECLS
+
+/** Only dispatch shapes effectively visible in the request view. */
+#define BSG_RENDER_FLAG_VISIBLE_ONLY      0x01
+
+/** Realize typed payloads for every qualifying shape node before dispatch. */
+#define BSG_RENDER_FLAG_PAYLOAD_PREPARE   0x02
+
+/** Alias for payload realization before backend dispatch. */
+#define BSG_RENDER_FLAG_PAYLOAD_DISPATCH  BSG_RENDER_FLAG_PAYLOAD_PREPARE
+
+/** Queue overlay items for dispatch after all solids. */
+#define BSG_RENDER_FLAG_OVERLAY_LAST      0x04
+
+/** Sort translucent shapes back-to-front before dispatching (placeholder). */
+#define BSG_RENDER_FLAG_SORTED_ALPHA      0x08
+
+/**
+ * Execute the HUD pass: collect the view HUD stream rather than the model
+ * draw stream, ordered by HUD metadata.  Call bsg_hud_sync() before
+ * collecting a HUD batch.
+ */
+#define BSG_RENDER_FLAG_HUD_PASS          0x10
+
+/**
+ * Compatibility flag: collect render items into the output item table set by
+ * bsg_render_request_set_output_items() when using bsg_render_request_execute().
+ *
+ * When this flag is set the compatibility executor populates the output table
+ * (which must be an initialised bu_ptbl allocated and owned by the caller)
+ * with pointers to heap-allocated bsg_render_item objects — one per
+ * qualifying shape.  Items are appended in phase order (OPAQUE →
+ * TRANSPARENT → OVERLAY → HUD) rather than tree-traversal order.  The caller
+ * is responsible for calling bsg_render_item_free() on each item and
+ * bu_ptbl_free() on the table.
+ *
+ * When this flag is clear (the default) items are allocated internally,
+ * dispatched to the adapter, and then freed
+ * before bsg_render_request_execute() returns.
+ */
+#define BSG_RENDER_FLAG_COLLECT_ITEMS     0x20
+
+struct bsg_render_request;
+struct bsg_render_batch;
+
+/**
+ * Allocate and return a render request with default flags
+ * (BSG_RENDER_FLAG_VISIBLE_ONLY | BSG_RENDER_FLAG_PAYLOAD_PREPARE).
+ * @p view and @p dmp are borrowed references — the request
+ * does not take ownership of them.
+ * Returns NULL on allocation failure.
+ */
+BSG_EXPORT extern struct bsg_render_request *
+bsg_render_request_create(struct bsg_view *view,
+			  void            *dmp);
+
+/**
+ * Release a render request previously allocated by
+ * bsg_render_request_create().
+ * The referenced view/dmp are NOT freed.
+ * No-op if @p req is NULL.
+ */
+BSG_EXPORT extern void
+bsg_render_request_destroy(struct bsg_render_request *req);
+
+BSG_EXPORT extern struct bsg_view *
+bsg_render_request_view(const struct bsg_render_request *req);
+
+BSG_EXPORT extern void *
+bsg_render_request_dmp(const struct bsg_render_request *req);
+
+BSG_EXPORT extern unsigned int
+bsg_render_request_flags(const struct bsg_render_request *req);
+
+BSG_EXPORT extern void
+bsg_render_request_set_flags(struct bsg_render_request *req, unsigned int flags);
+
+BSG_EXPORT extern void
+bsg_render_request_add_flags(struct bsg_render_request *req, unsigned int flags);
+
+BSG_EXPORT extern void
+bsg_render_request_set_adapter(struct bsg_render_request *req,
+			       struct bsg_backend_adapter *adapter);
+
+BSG_EXPORT extern void
+bsg_render_request_set_output_items(struct bsg_render_request *req,
+				    struct bu_ptbl *items);
+
+BSG_EXPORT extern struct bsg_render_settings *
+bsg_render_request_settings(struct bsg_render_request *req);
+
+BSG_EXPORT extern const struct bsg_render_settings *
+bsg_render_request_settings_const(const struct bsg_render_request *req);
+
+BSG_EXPORT extern void
+bsg_render_request_set_background(struct bsg_render_request *req,
+				  const unsigned char *background1,
+				  const unsigned char *background2);
+
+BSG_EXPORT extern void
+bsg_render_request_set_geometry_default_color(struct bsg_render_request *req,
+					      const unsigned char *color);
+
+BSG_EXPORT extern void
+bsg_render_request_set_clip(struct bsg_render_request *req,
+			    const vect_t *clipmin,
+			    const vect_t *clipmax,
+			    int zclip);
+
+BSG_EXPORT extern void
+bsg_render_request_set_lighting(struct bsg_render_request *req, int lighting);
+
+BSG_EXPORT extern struct bsg_render_batch *
+bsg_render_batch_create(void);
+
+BSG_EXPORT extern void
+bsg_render_batch_clear(struct bsg_render_batch *batch);
+
+BSG_EXPORT extern void
+bsg_render_batch_destroy(struct bsg_render_batch *batch);
+
+BSG_EXPORT extern size_t
+bsg_render_batch_count(const struct bsg_render_batch *batch);
+
+BSG_EXPORT extern const struct bsg_render_item *
+bsg_render_batch_get(const struct bsg_render_batch *batch, size_t idx);
+
+BSG_EXPORT extern size_t
+bsg_render_batch_move_items(struct bsg_render_batch *batch, struct bu_ptbl *dest);
+
+/**
+ * Resolve @p req's retained view stream into @p batch.
+ *
+ * The batch is cleared before collection.  Items are appended in render phase
+ * order and owned by the batch until bsg_render_batch_clear() or
+ * bsg_render_batch_destroy().
+ */
+BSG_EXPORT extern int
+bsg_render_request_collect(struct bsg_render_request *req,
+			   struct bsg_render_batch *batch);
+
+/**
+ * Dispatch an already-collected render batch through the request adapter.
+ *
+ * This is the backend-facing renderer entry point.  It reads only
+ * bsg_render_item records in @p batch and does not traverse the scene graph.
+ */
+BSG_EXPORT extern int
+bsg_render_batch_dispatch(struct bsg_render_request *req,
+			  const struct bsg_render_batch *batch);
+
+/**
+ * Compatibility wrapper:
+ *  1. Resolve the retained view stream and collect shape items with resolved transform and
+ *     appearance.
+ *  2. Sort and dispatch in phase order:
+ *     OPAQUE -> TRANSPARENT -> OVERLAY -> HUD.
+ *  3. For each item: call adapter prepare/draw callbacks when an adapter is
+ *     attached.
+ * Returns the number of shapes dispatched, or -1 if @p req is NULL.
+ */
+BSG_EXPORT extern int
+bsg_render_request_execute(struct bsg_render_request *req);
+
+__END_DECLS
+
+#endif /* BSG_RENDER_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/render_item.h

@@ -0,0 +1,395 @@
+/*                  R E N D E R _ I T E M . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Render item — the resolved, flat descriptor emitted by BSG traversal
+ * that a backend draws without further scene-graph access.
+ *
+ * During `bsg_render_request_collect` the renderer resolves each shape's
+ * accumulated world transform, appearance properties, payload type,
+ * visibility state, selection/highlight state, and LoD decision into a
+ * `bsg_render_item`.  Items are then sorted into four render phases and
+ * stored in a `bsg_render_batch`.  Payload realization is a distinct
+ * pre-render step; drawing no longer owns payload update policy.
+ *
+ * Backends receive items in this order:
+ *   BSG_RENDER_PHASE_OPAQUE → BSG_RENDER_PHASE_TRANSPARENT →
+ *   BSG_RENDER_PHASE_OVERLAY → BSG_RENDER_PHASE_HUD
+ *
+ * Within BSG_RENDER_PHASE_TRANSPARENT items are ordered back-to-front
+ * when `BSG_RENDER_FLAG_SORTED_ALPHA` is set on the request.
+ */
+/** @{ */
+/* @file bsg/render_item.h */
+
+#ifndef BSG_RENDER_ITEM_H
+#define BSG_RENDER_ITEM_H
+
+#include "common.h"
+
+#include "vmath.h"
+#include "bu/vls.h"
+#include "bsg/defines.h"
+#include "bsg/appearance_action.h"
+#include "bsg/faceplate.h"
+#include "bsg/feature.h"
+#include "bsg/payload.h"
+#include "bsg/render_settings.h"
+
+__BEGIN_DECLS
+
+struct bsg_mesh_lod;
+
+/**
+ * Render phase — controls the order in which items are dispatched.
+ *
+ * Phase ordering: OPAQUE (0) → TRANSPARENT (1) → OVERLAY (2) → HUD (3).
+ * Do not change the integer values; they serve as indices into the
+ * per-phase bucket arrays inside the render-request executor.
+ */
+typedef enum bsg_render_phase {
+    BSG_RENDER_PHASE_OPAQUE      = 0, /**< @brief  solid geometry, no alpha */
+    BSG_RENDER_PHASE_TRANSPARENT = 1, /**< @brief  geometry with transparency > 0 */
+    BSG_RENDER_PHASE_OVERLAY     = 2, /**< @brief  overlay shapes */
+    BSG_RENDER_PHASE_HUD         = 3, /**< @brief  HUD / faceplate shapes */
+    BSG_RENDER_PHASE_COUNT       = 4  /**< @brief  sentinel — number of phases */
+} bsg_render_phase;
+
+typedef enum bsg_render_geometry_kind {
+    BSG_RENDER_GEOMETRY_NONE = 0,
+    BSG_RENDER_GEOMETRY_MESH,
+    BSG_RENDER_GEOMETRY_LINE_SET,
+    BSG_RENDER_GEOMETRY_INDEXED_LINE_SET,
+    BSG_RENDER_GEOMETRY_POINT_SET,
+    BSG_RENDER_GEOMETRY_INDEXED_FACE_SET,
+    BSG_RENDER_GEOMETRY_TEXT,
+    BSG_RENDER_GEOMETRY_IMAGE,
+    BSG_RENDER_GEOMETRY_OVERLAY,
+    BSG_RENDER_GEOMETRY_HUD,
+    BSG_RENDER_GEOMETRY_ANNOTATION,
+    BSG_RENDER_GEOMETRY_CSG_PROXY,
+    BSG_RENDER_GEOMETRY_BREP_PROXY,
+    BSG_RENDER_GEOMETRY_EDIT_PREVIEW,
+    BSG_RENDER_GEOMETRY_EXTERNAL_PROXY
+} bsg_render_geometry_kind;
+
+typedef enum bsg_render_overlay_geometry_kind {
+    BSG_RENDER_OVERLAY_GEOMETRY_NONE = 0,
+    BSG_RENDER_OVERLAY_GEOMETRY_AXES,
+    BSG_RENDER_OVERLAY_GEOMETRY_GRID
+} bsg_render_overlay_geometry_kind;
+
+typedef enum bsg_render_image_kind {
+    BSG_RENDER_IMAGE_NONE = 0,
+    BSG_RENDER_IMAGE_RASTER,
+    BSG_RENDER_IMAGE_FRAMEBUFFER
+} bsg_render_image_kind;
+
+typedef enum bsg_render_surface_normal_kind {
+    BSG_RENDER_SURFACE_NORMALS_NONE = 0,
+    BSG_RENDER_SURFACE_NORMALS_PER_VERTEX,
+    BSG_RENDER_SURFACE_NORMALS_PER_FACE,
+    BSG_RENDER_SURFACE_NORMALS_PER_INDEX /**< @brief one normal per non-negative face-index entry */
+} bsg_render_surface_normal_kind;
+
+typedef enum bsg_render_proxy_kind {
+    BSG_RENDER_PROXY_NONE = 0,
+    BSG_RENDER_PROXY_CSG,
+    BSG_RENDER_PROXY_BREP,
+    BSG_RENDER_PROXY_EDIT_PREVIEW,
+    BSG_RENDER_PROXY_EXTERNAL
+} bsg_render_proxy_kind;
+
+struct bsg_render_proxy {
+    bsg_render_proxy_kind kind;
+    uint64_t source_identity;
+    uint64_t revision;
+};
+
+struct bsg_render_geometry {
+    bsg_render_geometry_kind kind;
+    uint64_t revision;
+    uint64_t source_identity;
+    size_t element_count;
+    struct {
+	char *label;
+	point_t position;
+	point_t target;
+	int size;
+	int line_flag;
+	int anchor;
+	int arrow;
+    } text;
+    struct {
+	point_t *points;
+	point_t *normals;
+	int *commands;
+	int *indices;
+	size_t point_count;
+	size_t normal_count;
+	size_t command_count;
+	size_t index_count;
+    } arrays;
+    struct {
+	bsg_render_overlay_geometry_kind kind;
+	struct bsg_axes axes;
+	struct bsg_grid_state grid;
+    } overlay;
+    struct {
+	bsg_render_image_kind kind;
+	size_t width;
+	size_t height;
+	size_t channels;
+	unsigned char *pixels;
+	size_t pixel_count;
+	int framebuffer_mode;
+    } image;
+    struct {
+	point_t *points;
+	vect_t *normals;
+	int *indices;
+	size_t point_count;
+	size_t normal_count;
+	size_t index_count;
+	size_t face_count;
+	bsg_render_surface_normal_kind normal_kind;
+	int material_valid;
+	struct bsg_resolved_appearance material;
+    } surface;
+    struct {
+	char *text;
+	bsg_annotation_space space;
+	point_t anchor;
+	mat_t model_mat;
+	mat_t display_mat;
+	point_t *points;
+	size_t point_count;
+	struct bsg_annotation_segment *segments;
+	size_t segment_count;
+    } annotation;
+    struct bsg_render_proxy proxy;
+    union {
+	const struct bsg_mesh_lod *mesh;
+    } data;
+};
+
+#define BSG_RENDER_FEATURE_ARROWS 0x01u
+
+typedef int (*bsg_render_segment_cb)(const point_t a,
+				     const point_t b,
+				     void *data);
+
+struct bsg_render_features {
+    unsigned int flags;
+    fastf_t arrow_tip_length;
+    fastf_t arrow_tip_width;
+    int hud_feature_type;
+};
+
+#define BSG_RENDER_ORDER_OPAQUE_CHILD_FIRST 0x01u
+
+typedef enum bsg_render_source_scope {
+    BSG_RENDER_SOURCE_SCOPE_UNKNOWN = 0,
+    BSG_RENDER_SOURCE_SCOPE_DATABASE,
+    BSG_RENDER_SOURCE_SCOPE_VIEW_SHARED,
+    BSG_RENDER_SOURCE_SCOPE_VIEW_LOCAL,
+    BSG_RENDER_SOURCE_SCOPE_INTERNAL_CHILD
+} bsg_render_source_scope;
+
+typedef enum bsg_render_geometry_role {
+    BSG_RENDER_GEOMETRY_ROLE_UNKNOWN = 0,
+    BSG_RENDER_GEOMETRY_ROLE_DATABASE_OBJECT,
+    BSG_RENDER_GEOMETRY_ROLE_VIEW_OVERLAY,
+    BSG_RENDER_GEOMETRY_ROLE_LINE_SET,
+    BSG_RENDER_GEOMETRY_ROLE_TEXT_LABEL,
+    BSG_RENDER_GEOMETRY_ROLE_AXES_WIDGET,
+    BSG_RENDER_GEOMETRY_ROLE_POLYGON_REGION,
+    BSG_RENDER_GEOMETRY_ROLE_HUD,
+    BSG_RENDER_GEOMETRY_ROLE_IMAGE,
+    BSG_RENDER_GEOMETRY_ROLE_MESH
+} bsg_render_geometry_role;
+
+typedef enum bsg_render_draw_intent {
+    BSG_RENDER_DRAW_INTENT_UNKNOWN = 0,
+    BSG_RENDER_DRAW_INTENT_DATABASE,
+    BSG_RENDER_DRAW_INTENT_VIEW_FEATURE,
+    BSG_RENDER_DRAW_INTENT_OVERLAY,
+    BSG_RENDER_DRAW_INTENT_HUD,
+    BSG_RENDER_DRAW_INTENT_EDIT_PREVIEW,
+    BSG_RENDER_DRAW_INTENT_INTERNAL
+} bsg_render_draw_intent;
+
+struct bsg_render_source {
+    uint64_t source_id;        /**< @brief stable drawable-source identity */
+    uint64_t geometry_id;      /**< @brief backend geometry source identity */
+    uint64_t lod_id;           /**< @brief LoD selector identity, 0 if none */
+    uint64_t lod_policy_id;    /**< @brief selected LoD/source-policy identity, 0 if none */
+    const char *name;          /**< @brief borrowed source/display name */
+    bsg_render_source_scope scope;
+    bsg_render_geometry_role geometry_role;
+    bsg_render_draw_intent draw_intent;
+    enum bsg_feature_family feature_family;
+    bsg_overlay_role overlay_role;
+    bsg_overlay_class overlay_class;
+    int non_database_source;
+};
+
+struct bsg_render_context {
+    mat_t model2view;
+    mat_t view2model;
+    mat_t projection;
+    int has_projection;
+    vect_t clipmin;
+    vect_t clipmax;
+    int zclip;
+    int lighting;
+    int viewport_width;
+    int viewport_height;
+    unsigned char background1[3];
+    unsigned char background2[3];
+    unsigned char geometry_default_color[3];
+    unsigned int request_flags;
+    unsigned int backend_capabilities;
+    int hud_pass;
+    int overlay_pass;
+    uint64_t settings_hash;
+    struct bsg_render_settings settings;
+};
+
+
+/**
+ * A fully resolved, flat description of one drawable shape.
+ *
+ * Produced by `bsg_render_request_collect` from the view's retained stream.
+ * Graph-node pointers are render-construction context only and are not part
+ * of this backend contract.  Backends consume `source`, `geometry`,
+ * `features`, `appearance`, and `context` instead of dereferencing the graph.
+ * The `model_mat` is the accumulated product of all `BSG_NODE_TRANSFORM`
+ * ancestor matrices at the time the shape was visited.
+ */
+struct bsg_render_item {
+    struct bsg_view   *view;          /**< @brief  request view context (borrowed) */
+    mat_t              model_mat;     /**< @brief  accumulated model-to-world matrix */
+    struct bsg_render_source source;  /**< @brief  backend-facing source identity */
+    struct bsg_render_context context; /**< @brief request/batch metadata snapshot */
+    const char        *name;          /**< @brief  source node name (borrowed) */
+    uint64_t           payload_revision; /**< @brief typed payload revision captured for this item */
+    uint64_t           cache_identity;/**< @brief  resolved backend cache identity */
+    bsg_payload_realization_kind realization_kind; /**< @brief payload realization domain */
+    bsg_payload_realization_status realization_status; /**< @brief current/stale/failed */
+    bsg_payload_stale_reason stale_reason; /**< @brief why payload realization is stale */
+
+    /**
+     * Fully resolved appearance.
+     *
+     * Populated during bsg_render_request_collect.
+     * Backends MUST read appearance fields from here and must NOT re-derive
+     * them by accessing node internals during drawing.
+     */
+    struct bsg_resolved_appearance appearance;
+
+    /* Geometry / phase classification */
+    struct bsg_render_geometry geometry; /**< @brief backend-facing geometry view */
+    struct bsg_render_features features; /**< @brief resolved feature-node behavior */
+    bsg_render_phase   phase;         /**< @brief  render phase this item belongs to */
+
+    /* Resolved visibility and selection semantics. */
+    int                visible;       /**< @brief  effective visibility in item->view */
+    int                force_draw;    /**< @brief  effective force-draw bypass */
+    int                highlighted;   /**< @brief  resolved highlight state */
+    int                selected;      /**< @brief  selection highlight compatibility state */
+
+    /* Resolved draw bounds used by backends for small-object culling. */
+    fastf_t            bounds_radius; /**< @brief  model-space bounding sphere radius */
+    point_t            bounds_center; /**< @brief  model-space bounding sphere center */
+    int                non_database_source;/**< @brief  non-database feature or overlay source */
+    int                has_bounds; /**< @brief bounds_center and bounds_radius are valid */
+    int                graph_depth; /**< @brief scene-graph depth captured during traversal */
+    size_t             sequence; /**< @brief collection order within the render request */
+    unsigned int       order_flags; /**< @brief BSG_RENDER_ORDER_* traversal ordering hints */
+
+    /* Resolved LoD decision. */
+    int                lod_level;     /**< @brief  active LoD level, or -1 */
+    int                lod_level_count; /**< @brief  number of physical LoD levels */
+
+    /**
+     * Within-phase ordering hint.
+     *
+     * For BSG_RENDER_PHASE_TRANSPARENT: a larger value means the item is
+     * farther from the camera and should be drawn first (back-to-front).
+     * For BSG_RENDER_PHASE_HUD: corresponds to bsg_hud_node_meta::sort_order.
+     * For other phases: 0 (insertion order, except opaque child-before-parent
+     * dispatch uses graph_depth).
+     */
+    int                sort_key;
+};
+
+
+/* -----------------------------------------------------------------------
+ * Item lifecycle
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Allocate and zero-initialise a render item.
+ * Returns NULL on allocation failure.
+ * The caller owns the returned item and must release it with
+ * bsg_render_item_free().
+ */
+BSG_EXPORT extern struct bsg_render_item *
+bsg_render_item_create(void);
+
+BSG_EXPORT extern size_t
+bsg_render_item_foreach_line_segment(const struct bsg_render_item *item,
+				     bsg_render_segment_cb cb,
+				     void *data);
+
+BSG_EXPORT extern int
+bsg_render_item_has_line_segments(const struct bsg_render_item *item);
+
+BSG_EXPORT extern size_t
+bsg_render_item_foreach_wire_segment(const struct bsg_render_item *item,
+				     bsg_render_segment_cb cb,
+				     void *data);
+
+BSG_EXPORT extern int
+bsg_render_item_has_wire_segments(const struct bsg_render_item *item);
+
+/**
+ * Release a render item previously allocated by bsg_render_item_create().
+ * No-op if @p item is NULL.
+ */
+BSG_EXPORT extern void
+bsg_render_item_free(struct bsg_render_item *item);
+
+__END_DECLS
+
+#endif /* BSG_RENDER_ITEM_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/render_settings.h

@@ -0,0 +1,269 @@
+/*             R E N D E R _ S E T T I N G S . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Render settings — per-view rendering policy.
+ *
+ * A `bsg_render_settings` collects the draw-mode, hidden-line, z-clip,
+ * transparency, LoD, framebuffer, and HUD enablement knobs that control
+ * how `bsg_render_request_collect` resolves render batches.  The struct is attached to
+ * a `bsg_view` (or to a `bsg_view_set` for shared-settings layouts) and
+ * is consumed from the render request rather than being read from scattered
+ * view storage fields during traversal.
+ *
+ * The struct is intentionally plain-old-data so it can be cheaply
+ * copied for e.g. snapshot/restore.
+ */
+/** @{ */
+/* @file bsg/render_settings.h */
+
+#ifndef BSG_RENDER_SETTINGS_H
+#define BSG_RENDER_SETTINGS_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+/* -----------------------------------------------------------------------
+ * Transparency policy
+ * ----------------------------------------------------------------------- */
+
+/** How transparent items are blended. */
+typedef enum bsg_transparency_policy {
+    /** No transparency: all items rendered opaque. */
+    BSG_TRANSPARENCY_NONE     = 0,
+    /** Depth-sorted back-to-front alpha blending. */
+    BSG_TRANSPARENCY_SORTED   = 1,
+    /** Order-independent transparency (if the backend supports it). */
+    BSG_TRANSPARENCY_OIT      = 2
+} bsg_transparency_policy;
+
+
+/* -----------------------------------------------------------------------
+ * LoD policy
+ * ----------------------------------------------------------------------- */
+
+/** How level-of-detail is selected during traversal. */
+typedef enum bsg_lod_policy {
+    /** LoD selection disabled: always render the highest-detail level (0). */
+    BSG_LOD_OFF              = 0,
+    /** Automatic LoD selection based on screen-space size estimate. */
+    BSG_LOD_AUTO             = 1,
+    /** Force a specific LoD level for all nodes (level stored separately). */
+    BSG_LOD_FORCE_LEVEL      = 2
+} bsg_lod_policy;
+
+struct bsg_lod_source_policy_settings {
+    /** Level-of-detail selection policy. */
+    bsg_lod_policy policy;
+
+    /** Forced LoD level when policy == BSG_LOD_FORCE_LEVEL. */
+    int forced_level;
+
+    /** Non-zero enables mesh/BoT LoD source selection. */
+    int mesh_enabled;
+
+    /** Non-zero enables CSG view-dependent source selection. */
+    int csg_enabled;
+
+    /** Non-zero requests redraw/refresh when view zoom changes. */
+    int zoom_refresh;
+
+    /** LoD scale factor.  1.0 = neutral. */
+    fastf_t scale;
+
+    /** BoT face threshold for choosing the LoD mesh source. */
+    size_t bot_threshold;
+
+    /** Curve scale for view-dependent primitive realization. */
+    fastf_t curve_scale;
+
+    /** Point scale for view-dependent primitive realization. */
+    fastf_t point_scale;
+};
+
+
+/* -----------------------------------------------------------------------
+ * Framebuffer mode
+ * ----------------------------------------------------------------------- */
+
+/** How a linked framebuffer is composited with the scene. */
+typedef enum bsg_framebuffer_mode {
+    /** Framebuffer display disabled. */
+    BSG_FB_OFF               = 0,
+    /** Framebuffer drawn as an overlay on top of the 3-D scene. */
+    BSG_FB_OVERLAY           = 1,
+    /** Framebuffer drawn as an underlay beneath the 3-D scene. */
+    BSG_FB_UNDERLAY          = 2
+} bsg_framebuffer_mode;
+
+
+/* -----------------------------------------------------------------------
+ * Render settings struct
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Rendering policy settings for a BSG render request.
+ *
+ * Allocate with bsg_render_settings_create(); release with
+ * bsg_render_settings_destroy().  Alternatively, fill in a stack-allocated
+ * struct with bsg_render_settings_init_defaults() and populate from a view
+ * with bsg_render_settings_from_view().
+ */
+struct bsg_render_settings {
+
+    /* ----- Draw mode --------------------------------------------------- */
+
+    /**
+     * Default display mode for shapes that have no per-node appearance override.
+     *   0 = wireframe
+     *   1 = shaded BoT/polysolid only (boolean NOT evaluated)
+     *   2 = shaded (boolean NOT evaluated)
+     *   3 = shaded (boolean evaluated)
+     *   4 = hidden-line
+     */
+    int             draw_mode;
+
+    /* ----- Z-clip ------------------------------------------------------ */
+
+    /** Non-zero enables Z-plane clipping during traversal. */
+    int             zclip;
+
+    /* ----- Transparency ------------------------------------------------- */
+
+    /** Transparency rendering policy (see bsg_transparency_policy). */
+    bsg_transparency_policy  transparency_policy;
+
+    /* ----- LoD ---------------------------------------------------------- */
+
+    struct bsg_lod_source_policy_settings lod_source_policy;
+
+    /* ----- Framebuffer -------------------------------------------------- */
+
+    /** Framebuffer compositing mode (see bsg_framebuffer_mode). */
+    bsg_framebuffer_mode  fb_mode;
+
+    /* ----- HUD ---------------------------------------------------------- */
+
+    /** Non-zero enables the HUD render pass after the 3-D scene. */
+    int             hud_enabled;
+
+    /**
+     * Non-zero enables the view-scale HUD feature specifically.
+     * Respected only when hud_enabled is non-zero.
+     */
+    int             hud_view_scale;
+
+    /**
+     * Non-zero enables the view-parameters HUD feature.
+     * Respected only when hud_enabled is non-zero.
+     */
+    int             hud_view_params;
+
+    /* ----- Geometry default color -------------------------------------- */
+
+    /**
+     * Default wireframe RGB color used for geometry whose node requested
+     * the renderer's default color and that carries no
+     * per-node command color override.
+     *
+     * This is the policy input render collection reads when modeling the
+     * geometry-default-color appearance layer, so backends no longer have
+     * to re-derive it during draw.  Backends that own a default color
+     * (e.g. libdm's dm_get_geometry_default_color) set it on the render
+     * request before traversal.  Defaults to red {255,0,0}.
+     */
+    unsigned char   geometry_default_color[3];
+};
+
+
+/* -----------------------------------------------------------------------
+ * Lifecycle
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Allocate a bsg_render_settings with default values.
+ * Returns NULL on allocation failure.
+ */
+BSG_EXPORT extern struct bsg_render_settings *
+bsg_render_settings_create(void);
+
+/**
+ * Release a bsg_render_settings previously allocated by
+ * bsg_render_settings_create().
+ * No-op if @p rs is NULL.
+ */
+BSG_EXPORT extern void
+bsg_render_settings_destroy(struct bsg_render_settings *rs);
+
+/**
+ * Fill @p rs with conservative defaults:
+ *   draw_mode = 0 (wireframe), zclip = 0, transparency_policy = SORTED,
+ *   lod_source_policy.policy = AUTO, lod_source_policy.scale = 1.0,
+ *   fb_mode = OFF, hud_enabled = 1.
+ * No-op if @p rs is NULL.
+ */
+BSG_EXPORT extern void
+bsg_render_settings_init_defaults(struct bsg_render_settings *rs);
+
+/**
+ * Populate @p rs from @p v's canonical view-state render policy.
+ *
+ * No-op if either argument is NULL.
+ */
+BSG_EXPORT extern void
+bsg_render_settings_from_view(struct bsg_render_settings *rs,
+			       const struct bsg_view *v);
+
+/**
+ * Write the render-policy fields of @p rs back into @p v's canonical
+ * view-state render policy.
+ *
+ * This is the inverse of bsg_render_settings_from_view: it lets a consumer
+ * (e.g. a settings panel or a libged view subcommand) edit a render-settings
+ * object and then flush the changes into the view-state record.
+ * Only the data/render-policy fields that round-trip through
+ * bsg_render_settings_from_view are written (zclip, framebuffer mode,
+ * adaptive plotting, LoD scale, HUD faceplate enable flags); fields that have
+ * no current view-state backing are ignored.
+ *
+ * No-op if either argument is NULL.
+ */
+BSG_EXPORT extern void
+bsg_render_settings_apply_to_view(const struct bsg_render_settings *rs,
+				  struct bsg_view *v);
+
+__END_DECLS
+
+#endif /* BSG_RENDER_SETTINGS_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/scene_builder.h

@@ -0,0 +1,193 @@
+/*                S C E N E _ B U I L D E R . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Typed scene construction API.
+ *
+ * This interface is the preferred scene authoring surface for producers.  It
+ * exposes semantic elements and opaque references rather than generic graph
+ * node allocation.  References returned by the element create functions are
+ * owning handles and are released with bsg_scene_ref_destroy().  References
+ * returned by bsg_view_scene_ref() or bsg_view_scene_ref_ensure() are borrowed
+ * view attachments; detach them from the view with bsg_view_scene_ref_detach()
+ * and do not destroy them directly.
+ */
+/** @{ */
+/* @file bsg/scene_builder.h */
+
+#ifndef BSG_SCENE_BUILDER_H
+#define BSG_SCENE_BUILDER_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+typedef struct bsg_scene_ref {
+    void *opaque;
+} bsg_scene_ref;
+
+#define BSG_SCENE_REF_NULL_INIT { NULL }
+
+enum bsg_scene_element_type {
+    BSG_SCENE_ELEMENT_NONE = 0,
+    BSG_SCENE_ELEMENT_GROUP,
+    BSG_SCENE_ELEMENT_SHAPE,
+    BSG_SCENE_ELEMENT_TRANSFORM,
+    BSG_SCENE_ELEMENT_VIEW_SCOPE,
+    BSG_SCENE_ELEMENT_LOD
+};
+
+BSG_EXPORT extern bsg_scene_ref
+bsg_scene_ref_null(void);
+
+BSG_EXPORT extern int
+bsg_scene_ref_is_null(bsg_scene_ref ref);
+
+BSG_EXPORT extern int
+bsg_scene_ref_equal(bsg_scene_ref a, bsg_scene_ref b);
+
+BSG_EXPORT extern enum bsg_scene_element_type
+bsg_scene_ref_type(bsg_scene_ref ref);
+
+BSG_EXPORT extern bsg_scene_ref
+bsg_scene_group_create(struct bsg_view *v, const char *name);
+
+BSG_EXPORT extern bsg_scene_ref
+bsg_scene_shape_create(struct bsg_view *v, const char *name);
+
+BSG_EXPORT extern bsg_scene_ref
+bsg_scene_transform_create(struct bsg_view *v, const mat_t mat, const char *name);
+
+BSG_EXPORT extern bsg_scene_ref
+bsg_scene_view_scope_create(struct bsg_view *v, const char *name);
+
+BSG_EXPORT extern bsg_scene_ref
+bsg_view_scene_ref(const struct bsg_view *v);
+
+BSG_EXPORT extern bsg_scene_ref
+bsg_view_scene_ref_ensure(struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_scene_ref_detach(struct bsg_view *v);
+
+BSG_EXPORT extern int
+bsg_view_scene_ref_attach(struct bsg_view *v, bsg_scene_ref root);
+
+BSG_EXPORT extern void
+bsg_scene_ref_destroy(bsg_scene_ref ref);
+
+BSG_EXPORT extern void
+bsg_scene_set_name(bsg_scene_ref ref, const char *name);
+
+BSG_EXPORT extern const char *
+bsg_scene_name(bsg_scene_ref ref);
+
+BSG_EXPORT extern void
+bsg_scene_set_visible(bsg_scene_ref ref, int visible);
+
+BSG_EXPORT extern int
+bsg_scene_visible(bsg_scene_ref ref);
+
+BSG_EXPORT extern void
+bsg_scene_set_color(bsg_scene_ref ref, unsigned char r, unsigned char g, unsigned char b);
+
+BSG_EXPORT extern void
+bsg_scene_color(bsg_scene_ref ref, unsigned char *r, unsigned char *g, unsigned char *b);
+
+BSG_EXPORT extern void
+bsg_scene_set_transform(bsg_scene_ref ref, const mat_t mat);
+
+BSG_EXPORT extern void
+bsg_scene_transform(bsg_scene_ref ref, mat_t mat);
+
+BSG_EXPORT extern void
+bsg_scene_set_bounds(bsg_scene_ref ref, const point_t bmin, const point_t bmax, int valid);
+
+BSG_EXPORT extern int
+bsg_scene_bounds(bsg_scene_ref ref, point_t bmin, point_t bmax);
+
+BSG_EXPORT extern struct bsg_view *
+bsg_scene_view(bsg_scene_ref ref);
+
+BSG_EXPORT extern int
+bsg_scene_is_view_scope(bsg_scene_ref ref);
+
+BSG_EXPORT extern int
+bsg_scene_is_database_source(bsg_scene_ref ref);
+
+BSG_EXPORT extern void
+bsg_scene_mark_db_object(bsg_scene_ref shape);
+
+BSG_EXPORT extern void
+bsg_scene_set_non_database_source(bsg_scene_ref shape, int non_database_source);
+
+BSG_EXPORT extern int
+bsg_scene_is_view_source(bsg_scene_ref ref);
+
+BSG_EXPORT extern int
+bsg_scene_is_local_source(bsg_scene_ref ref);
+
+BSG_EXPORT extern void
+bsg_scene_set_view(bsg_scene_ref ref, struct bsg_view *v);
+
+BSG_EXPORT extern int
+bsg_scene_update_bounds(bsg_scene_ref ref, struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_scene_invalidate(bsg_scene_ref ref);
+
+BSG_EXPORT extern fastf_t
+bsg_scene_view_depth(bsg_scene_ref ref, struct bsg_view *v, int mode);
+
+BSG_EXPORT extern void
+bsg_scene_append_child(bsg_scene_ref parent, bsg_scene_ref child);
+
+BSG_EXPORT extern void
+bsg_scene_remove_child(bsg_scene_ref parent, bsg_scene_ref child);
+
+BSG_EXPORT extern bsg_scene_ref
+bsg_scene_parent(bsg_scene_ref ref);
+
+BSG_EXPORT extern size_t
+bsg_scene_child_count(bsg_scene_ref ref);
+
+BSG_EXPORT extern bsg_scene_ref
+bsg_scene_child_at(bsg_scene_ref ref, size_t idx);
+
+BSG_EXPORT extern bsg_scene_ref
+bsg_scene_find_child(bsg_scene_ref parent, const char *name);
+
+__END_DECLS
+
+#endif /* BSG_SCENE_BUILDER_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/scene_object.h

@@ -1,7 +1,7 @@
-/*                        B V . H
+/*                    S C E N E _ O B J E C T . H
  * BRL-CAD
  *
- * Copyright (c) 1993-2026 United States Government as represented by
+ * Copyright (c) 2026 United States Government as represented by
  * the U.S. Army Research Laboratory.
  *
  * This library is free software; you can redistribute it and/or
@@ -17,39 +17,34 @@
  * License along with this file; see the file named COPYING for more
  * information.
  */
-
-// TODO - bv currently conflates scene and camera concepts - for example,
-// data axes and polygons are properly scene objects being viewed by the
-// camera, but at the moment they're directly part of the bv struct.
-//
-// The plan is to address this, so until this notice is removed the bv data
-// structure and related data structures should be considered in flux.
-
-/** @addtogroup libbv */
-/** @{ */
-/** @file bv.h
+/** @addtogroup libbsg
  *
+ * @brief
+ * Semantic scene-object query APIs.
+ *
+ * Public callers may visit database-derived scene nodes or request scene
+ * bounds updates through this header.  Storage-level node allocation,
+ * lifecycle callbacks, node lookup tables, and mutable geometry lists are
+ * private implementation details.
  */
+/** @{ */
+/* @file bsg/scene_object.h */
 
-#ifndef BV_H
-#define BV_H
+#ifndef BSG_SCENE_OBJECT_H
+#define BSG_SCENE_OBJECT_H
 
 #include "common.h"
-
 #include "vmath.h"
-#include "bu/vls.h"
-#include "bn.h"
+#include "bsg/defines.h"
 
-#include "./bv/defines.h"
-#include "./bv/adc.h"
-#include "./bv/lod.h"
-#include "./bv/polygon.h"
-#include "./bv/snap.h"
-#include "./bv/util.h"
-#include "./bv/vlist.h"
-#include "./bv/view_sets.h"
+__BEGIN_DECLS
 
-#endif /* BV_H */
+/* Public scene-object identity and bounds operations are exposed through
+ * typed refs, feature records, render records, and scene-builder APIs. */
+
+__END_DECLS
+
+#endif /* BSG_SCENE_OBJECT_H */
 
 /** @} */
 /*

include/bsg/scene_set.h

@@ -0,0 +1,79 @@
+/*                    S C E N E _ S E T . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * A bsg_scene_set manages per-view scene attachments across a set of views
+ * that share a GED instance.  It is reserved for future use when a
+ * centralised per-GED registry is needed.
+ */
+/** @{ */
+/* @file bsg/scene_set.h */
+
+#ifndef BSG_SCENE_SET_H
+#define BSG_SCENE_SET_H
+
+#include "common.h"
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+/**
+ * Opaque per-GED scene root registry.
+ */
+struct bsg_scene_set;
+
+/**
+ * Allocate an empty bsg_scene_set.
+ */
+BSG_EXPORT extern struct bsg_scene_set *
+bsg_scene_set_create(void);
+
+/**
+ * Free a bsg_scene_set (does NOT free the scene roots stored inside it).
+ */
+BSG_EXPORT extern void
+bsg_scene_set_destroy(struct bsg_scene_set *ss);
+
+/**
+ * Scene roots are registered through implementation-private storage while the
+ * public API is finalized around scene refs.
+ */
+
+/**
+ * Remove the entry for @p v from @p ss (does NOT free the stored scene).
+ */
+BSG_EXPORT extern void
+bsg_scene_set_remove(struct bsg_scene_set *ss, struct bsg_view *v);
+
+__END_DECLS
+
+#endif /* BSG_SCENE_SET_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/selection.h

@@ -0,0 +1,103 @@
+/*                   S E L E C T I O N . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * First-class selection model for BSG interaction records.
+ *
+ * A `bsg_selection` is an opaque set of cloned interaction records.  The
+ * records carry feature refs, source paths, subelement ids, and payload
+ * hit ids; graph-node pointers are not selection identity.
+ */
+/** @{ */
+/* @file bsg/selection.h */
+
+#ifndef BSG_SELECTION_H
+#define BSG_SELECTION_H
+
+#include "common.h"
+#include "bu/ptbl.h"
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+/** Opaque selection-set handle */
+struct bsg_selection;
+struct bsg_interaction_record;
+
+/**
+ * Allocate and initialise an empty selection set.
+ * Returns NULL on allocation failure.
+ */
+BSG_EXPORT extern struct bsg_selection *
+bsg_selection_create(void);
+
+/**
+ * Release a selection set.
+ * Source objects referenced by the set are NOT destroyed; only the set itself
+ * is freed.
+ * No-op if @p sel is NULL.
+ */
+BSG_EXPORT extern void
+bsg_selection_destroy(struct bsg_selection *sel);
+
+BSG_EXPORT extern void
+bsg_selection_add_record(struct bsg_selection *sel,
+			 const struct bsg_interaction_record *record);
+
+BSG_EXPORT extern void
+bsg_selection_remove_record(struct bsg_selection *sel,
+			    const struct bsg_interaction_record *record);
+
+/**
+ * Remove all records from @p sel.
+ * No-op if @p sel is NULL.
+ */
+BSG_EXPORT extern void
+bsg_selection_clear(struct bsg_selection *sel);
+
+BSG_EXPORT extern int
+bsg_selection_contains_record(const struct bsg_selection *sel,
+			      const struct bsg_interaction_record *record);
+
+/**
+ * Return the number of interaction records currently in @p sel.
+ * Returns 0 if @p sel is NULL.
+ */
+BSG_EXPORT extern size_t
+bsg_selection_count(const struct bsg_selection *sel);
+
+BSG_EXPORT extern const struct bsg_interaction_record *
+bsg_selection_record(const struct bsg_selection *sel, size_t idx);
+
+__END_DECLS
+
+#endif /* BSG_SELECTION_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/sensor.h

@@ -0,0 +1,120 @@
+/*                      S E N S O R . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Public typed sensor API.
+ *
+ * Sensor refs are owning handles.  Destroy them with bsg_sensor_ref_destroy()
+ * or a typed destroy helper.  Field and node sensor targets are borrowed refs;
+ * callers must destroy sensors before destroying their watched field or node.
+ * Timer and update sensors are manually triggered by this API.
+ */
+/** @{ */
+/* @file bsg/sensor.h */
+
+#ifndef BSG_SENSOR_H
+#define BSG_SENSOR_H
+
+#include "common.h"
+#include <stdint.h>
+#include "bsg/field.h"
+
+__BEGIN_DECLS
+
+typedef enum bsg_sensor_kind {
+    BSG_SENSOR_KIND_INVALID = 0,
+    BSG_SENSOR_KIND_FIELD,
+    BSG_SENSOR_KIND_NODE,
+    BSG_SENSOR_KIND_TIMER,
+    BSG_SENSOR_KIND_UPDATE
+} bsg_sensor_kind;
+
+typedef struct bsg_sensor_ref {
+    void *opaque;
+    uint64_t generation;
+} bsg_sensor_ref;
+
+typedef struct bsg_field_sensor_ref { bsg_sensor_ref sensor; } bsg_field_sensor_ref;
+typedef struct bsg_node_sensor_ref { bsg_sensor_ref sensor; } bsg_node_sensor_ref;
+typedef struct bsg_timer_sensor_ref { bsg_sensor_ref sensor; } bsg_timer_sensor_ref;
+typedef struct bsg_update_sensor_ref { bsg_sensor_ref sensor; } bsg_update_sensor_ref;
+
+#define BSG_SENSOR_REF_NULL_INIT { NULL, 0 }
+#define BSG_FIELD_REF_SENSOR_NULL_INIT { BSG_SENSOR_REF_NULL_INIT }
+#define BSG_NODE_REF_SENSOR_NULL_INIT { BSG_SENSOR_REF_NULL_INIT }
+#define BSG_TIMER_REF_SENSOR_NULL_INIT { BSG_SENSOR_REF_NULL_INIT }
+#define BSG_UPDATE_REF_SENSOR_NULL_INIT { BSG_SENSOR_REF_NULL_INIT }
+
+typedef int (*bsg_field_sensor_cb)(bsg_field_ref field, void *data);
+typedef int (*bsg_node_sensor_cb)(bsg_node_ref node, bsg_field_ref changed_field, void *data);
+typedef int (*bsg_timer_sensor_cb)(bsg_timer_sensor_ref sensor, void *data);
+typedef int (*bsg_update_sensor_cb)(bsg_update_sensor_ref sensor, void *data);
+
+BSG_EXPORT extern bsg_sensor_ref bsg_sensor_ref_null(void);
+BSG_EXPORT extern int bsg_sensor_ref_is_null(bsg_sensor_ref ref);
+BSG_EXPORT extern int bsg_sensor_ref_equal(bsg_sensor_ref a, bsg_sensor_ref b);
+BSG_EXPORT extern bsg_sensor_kind bsg_sensor_ref_kind(bsg_sensor_ref ref);
+BSG_EXPORT extern void bsg_sensor_ref_destroy(bsg_sensor_ref ref);
+
+BSG_EXPORT extern bsg_sensor_ref bsg_field_sensor_ref_as_sensor(bsg_field_sensor_ref ref);
+BSG_EXPORT extern bsg_sensor_ref bsg_node_sensor_ref_as_sensor(bsg_node_sensor_ref ref);
+BSG_EXPORT extern bsg_sensor_ref bsg_timer_sensor_ref_as_sensor(bsg_timer_sensor_ref ref);
+BSG_EXPORT extern bsg_sensor_ref bsg_update_sensor_ref_as_sensor(bsg_update_sensor_ref ref);
+
+BSG_EXPORT extern bsg_field_sensor_ref bsg_field_sensor_ref_create(bsg_field_ref field,
+								    bsg_field_sensor_cb cb,
+								    void *data);
+BSG_EXPORT extern bsg_node_sensor_ref bsg_node_sensor_ref_create(bsg_node_ref node,
+								 bsg_node_sensor_cb cb,
+								 void *data);
+BSG_EXPORT extern bsg_timer_sensor_ref bsg_timer_sensor_ref_create(long interval_ms,
+								   bsg_timer_sensor_cb cb,
+								   void *data);
+BSG_EXPORT extern bsg_update_sensor_ref bsg_update_sensor_ref_create(bsg_update_sensor_cb cb,
+								      void *data);
+
+BSG_EXPORT extern void bsg_field_sensor_ref_destroy(bsg_field_sensor_ref ref);
+BSG_EXPORT extern void bsg_node_sensor_ref_destroy(bsg_node_sensor_ref ref);
+BSG_EXPORT extern void bsg_timer_sensor_ref_destroy(bsg_timer_sensor_ref ref);
+BSG_EXPORT extern void bsg_update_sensor_ref_destroy(bsg_update_sensor_ref ref);
+
+BSG_EXPORT extern bsg_field_ref bsg_field_sensor_ref_field(bsg_field_sensor_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_node_sensor_ref_node(bsg_node_sensor_ref ref);
+BSG_EXPORT extern long bsg_timer_sensor_ref_interval_ms(bsg_timer_sensor_ref ref);
+
+BSG_EXPORT extern int bsg_timer_sensor_ref_trigger(bsg_timer_sensor_ref ref);
+BSG_EXPORT extern int bsg_update_sensor_ref_trigger(bsg_update_sensor_ref ref);
+BSG_EXPORT extern int bsg_update_sensors_fire(void);
+
+__END_DECLS
+
+#endif /* BSG_SENSOR_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/separator.h

@@ -0,0 +1,54 @@
+/*                    S E P A R A T O R . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Public typed separator child-list API.
+ */
+/** @{ */
+/* @file bsg/separator.h */
+
+#ifndef BSG_SEPARATOR_H
+#define BSG_SEPARATOR_H
+
+#include "common.h"
+#include "bsg/group.h"
+
+__BEGIN_DECLS
+
+BSG_EXPORT extern size_t bsg_separator_ref_child_count(bsg_separator_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_separator_ref_child_at(bsg_separator_ref ref, size_t idx);
+BSG_EXPORT extern void bsg_separator_ref_append_child(bsg_separator_ref parent, bsg_node_ref child);
+BSG_EXPORT extern void bsg_separator_ref_remove_child(bsg_separator_ref parent, bsg_node_ref child);
+
+__END_DECLS
+
+#endif /* BSG_SEPARATOR_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/snap.h

@@ -17,41 +17,38 @@
  * License along with this file; see the file named COPYING for more
  * information.
  */
-/** @addtogroup bv_snap
+/** @addtogroup bsg_snap
  *
  * @brief Logic for snapping sample points to view elements and grids.
  *
+ * Canonical home; bv/snap.h is a backward-compatibility bridge.
  */
 /** @{ */
-/** @file bv/snap.h */
+/** @file bsg/snap.h */
 
-#ifndef BV_SNAP_H
-#define BV_SNAP_H
+#ifndef BSG_SNAP_H
+#define BSG_SNAP_H
 
 #include "common.h"
 #include "vmath.h"
-#include "bv/defines.h"
+#include "bsg/defines.h"
 
 __BEGIN_DECLS
 
 /* Logic for snapping points to their closes view lines. */
 
-/* Snap sample 2D point to lines active in the view.  If populated,
- * v->gv_s->gv_snap_objs contains a subset of bv_scene_obj pointers indicating
- * which view objects to consider for snapping.  If nonzero,
- * v->gv_s->gv_snap_flags also tells the routine which categories of objects to
- * consider - objs objects will also be evaluated against the flags before
- * being used. */
-BV_EXPORT extern int bv_snap_lines_2d(struct bview *v, fastf_t *fx, fastf_t *fy);
+/* Snap sample 2D point to lines active in the view.  Snap object tables and
+ * source flags are read from the view-state snap source record. */
+BSG_EXPORT extern int bsg_snap_lines_2d(struct bsg_view *v, fastf_t *fx, fastf_t *fy);
 
-BV_EXPORT extern void bv_view_center_linesnap(struct bview *v);
+BSG_EXPORT extern void bsg_view_center_linesnap(struct bsg_view *v);
 
-BV_EXPORT extern int bv_snap_lines_3d(point_t *out_pt, struct bview *v, point_t *p);
-BV_EXPORT extern int bv_snap_grid_2d(struct bview *v, fastf_t *fx, fastf_t *fy);
+BSG_EXPORT extern int bsg_snap_lines_3d(point_t *out_pt, struct bsg_view *v, point_t *p);
+BSG_EXPORT extern int bsg_snap_grid_2d(struct bsg_view *v, fastf_t *fx, fastf_t *fy);
 
 __END_DECLS
 
-#endif /* BV_SNAP_H */
+#endif /* BSG_SNAP_H */
 
 /** @} */
 /*

include/bsg/snap_action.h

@@ -0,0 +1,82 @@
+/*                  S N A P _ A C T I O N . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @file bsg/snap_action.h */
+
+#ifndef BSG_SNAP_ACTION_H
+#define BSG_SNAP_ACTION_H
+
+#include "common.h"
+#include "vmath.h"
+#include "bu/vls.h"
+#include "bsg/defines.h"
+#include "bsg/feature.h"
+
+__BEGIN_DECLS
+
+typedef enum {
+    BSG_SNAP_KIND_GRID            = 0x01ULL,
+    BSG_SNAP_KIND_ENDPOINT        = 0x02ULL,
+    BSG_SNAP_KIND_MIDPOINT        = 0x04ULL,
+    BSG_SNAP_KIND_INTERSECTION    = 0x08ULL,
+    BSG_SNAP_KIND_PERPENDICULAR   = 0x10ULL,
+    BSG_SNAP_KIND_TANGENT         = 0x20ULL,
+    BSG_SNAP_KIND_OVERLAY_HANDLE  = 0x40ULL
+} bsg_snap_kind;
+
+typedef unsigned long long bsg_snap_kind_mask;
+
+struct bsg_snap_candidate {
+    point_t sc_point;
+    bsg_snap_kind sc_kind;
+    fastf_t sc_distance;
+    bsg_feature_ref sc_feature;
+    struct bu_vls sc_source_path;
+    int sc_stale;
+};
+
+struct bsg_snap_result {
+    struct bsg_snap_candidate *sr_candidates;
+    size_t sr_cnt;
+};
+
+BSG_EXPORT extern void
+bsg_snap_result_init(struct bsg_snap_result *out);
+
+BSG_EXPORT extern void
+bsg_snap_result_free(struct bsg_snap_result *out);
+
+BSG_EXPORT extern int
+bsg_snap_candidates(struct bsg_view *v, point_t sample, double tol,
+		    bsg_snap_kind_mask kinds, struct bsg_snap_result *out);
+
+/**
+ * Convenience wrapper: snap a 2D view-space point (vx, vy) using the
+ * specified snap-kind mask.  On success the pointed-to values are updated
+ * in place and 1 is returned; 0 means no snap occurred.  The caller
+ * already has 2D view coords; this avoids duplicating the 2D↔model
+ * conversion at every call site.
+ */
+BSG_EXPORT extern int
+bsg_snap_point_2d(struct bsg_view *v, fastf_t *vx, fastf_t *vy,
+		  bsg_snap_kind_mask kinds);
+
+__END_DECLS
+
+#endif /* BSG_SNAP_ACTION_H */

include/bsg/state.h

@@ -0,0 +1,157 @@
+/*                         S T A T E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Public traversal-state API.
+ *
+ * A bsg_state_ref is an owning handle to one resolved traversal-state frame.
+ * Actions push/copy state as they traverse the graph, and consumers read
+ * semantic state from the handle instead of probing graph internals.
+ */
+/** @{ */
+/* @file bsg/state.h */
+
+#ifndef BSG_STATE_H
+#define BSG_STATE_H
+
+#include "common.h"
+#include <stdint.h>
+#include "vmath.h"
+#include "bsg/lod.h"
+#include "bsg/node.h"
+#include "bsg/camera.h"
+#include "bsg/light.h"
+
+__BEGIN_DECLS
+
+typedef struct bsg_state_ref {
+    void *opaque;
+} bsg_state_ref;
+
+#define BSG_STATE_REF_NULL_INIT { NULL }
+
+BSG_EXPORT extern bsg_state_ref bsg_state_ref_null(void);
+BSG_EXPORT extern int bsg_state_ref_is_null(bsg_state_ref ref);
+BSG_EXPORT extern bsg_state_ref bsg_state_ref_create(void);
+BSG_EXPORT extern bsg_state_ref bsg_state_ref_copy(bsg_state_ref ref);
+BSG_EXPORT extern bsg_state_ref bsg_state_ref_push(bsg_state_ref parent);
+BSG_EXPORT extern void bsg_state_ref_pop(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_destroy(bsg_state_ref ref);
+
+BSG_EXPORT extern bsg_node_ref bsg_state_ref_root(bsg_state_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_state_ref_node(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_transform(bsg_state_ref ref, mat_t mat);
+BSG_EXPORT extern void bsg_state_ref_set_transform(bsg_state_ref ref, const mat_t mat);
+BSG_EXPORT extern void bsg_state_ref_multiply_transform(bsg_state_ref ref, const mat_t mat);
+
+BSG_EXPORT extern int bsg_state_ref_inherited_visible(bsg_state_ref ref);
+BSG_EXPORT extern int bsg_state_ref_visible(bsg_state_ref ref);
+BSG_EXPORT extern int bsg_state_ref_force_draw(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_visibility(bsg_state_ref ref,
+						    int inherited_visible,
+						    int visible,
+						    int force_draw);
+
+BSG_EXPORT extern int bsg_state_ref_selected(bsg_state_ref ref);
+BSG_EXPORT extern int bsg_state_ref_highlighted(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_selection(bsg_state_ref ref,
+						   int selected,
+						   int highlighted);
+
+BSG_EXPORT extern int bsg_state_ref_lod_level(bsg_state_ref ref);
+BSG_EXPORT extern int bsg_state_ref_lod_level_count(bsg_state_ref ref);
+BSG_EXPORT extern bsg_lod_source_ref bsg_state_ref_lod_source(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_lod(bsg_state_ref ref,
+					     bsg_lod_source_ref source,
+					     int level,
+					     int level_count);
+
+BSG_EXPORT extern int bsg_state_ref_render_phase(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_render_phase(bsg_state_ref ref, int phase);
+BSG_EXPORT extern int bsg_state_ref_view_scope_visible(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_view_scope_visible(bsg_state_ref ref, int visible);
+BSG_EXPORT extern uint64_t bsg_state_ref_source_identity(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_source_identity(bsg_state_ref ref, uint64_t source_identity);
+BSG_EXPORT extern unsigned int bsg_state_ref_backend_capabilities(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_backend_capabilities(bsg_state_ref ref, unsigned int capabilities);
+
+BSG_EXPORT extern void bsg_state_ref_material_color(bsg_state_ref ref, unsigned char color[3]);
+BSG_EXPORT extern void bsg_state_ref_set_material_color(bsg_state_ref ref, const unsigned char color[3]);
+BSG_EXPORT extern double bsg_state_ref_material_transparency(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_material_transparency(bsg_state_ref ref, double transparency);
+BSG_EXPORT extern int bsg_state_ref_has_material(bsg_state_ref ref);
+BSG_EXPORT extern uint32_t bsg_state_ref_material_revision(bsg_state_ref ref);
+BSG_EXPORT extern uint32_t bsg_state_ref_appearance_revision(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_appearance_revisions(bsg_state_ref ref,
+							      uint32_t material_revision,
+							      uint32_t appearance_revision);
+
+BSG_EXPORT extern int bsg_state_ref_draw_mode(bsg_state_ref ref);
+BSG_EXPORT extern int bsg_state_ref_line_width(bsg_state_ref ref);
+BSG_EXPORT extern int bsg_state_ref_line_style(bsg_state_ref ref);
+BSG_EXPORT extern int bsg_state_ref_has_draw_style(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_draw_style(bsg_state_ref ref,
+						    int draw_mode,
+						    int line_width,
+						    int line_style);
+BSG_EXPORT extern double bsg_state_ref_complexity(bsg_state_ref ref);
+BSG_EXPORT extern int bsg_state_ref_has_complexity(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_complexity(bsg_state_ref ref, double complexity);
+
+BSG_EXPORT extern int bsg_state_ref_has_camera(bsg_state_ref ref);
+BSG_EXPORT extern int bsg_state_ref_camera_projection(bsg_state_ref ref);
+BSG_EXPORT extern double bsg_state_ref_camera_perspective(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_camera_position(bsg_state_ref ref, point_t position);
+BSG_EXPORT extern void bsg_state_ref_camera_orientation(bsg_state_ref ref, mat_t orientation);
+BSG_EXPORT extern double bsg_state_ref_camera_near_distance(bsg_state_ref ref);
+BSG_EXPORT extern double bsg_state_ref_camera_far_distance(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_camera(bsg_state_ref ref,
+						int projection,
+						double perspective,
+						const point_t position,
+						const mat_t orientation,
+						double near_distance,
+						double far_distance);
+
+BSG_EXPORT extern int bsg_state_ref_has_light(bsg_state_ref ref);
+BSG_EXPORT extern int bsg_state_ref_light_type(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_light_position(bsg_state_ref ref, point_t position);
+BSG_EXPORT extern void bsg_state_ref_light_direction(bsg_state_ref ref, vect_t direction);
+BSG_EXPORT extern void bsg_state_ref_light_diffuse_color(bsg_state_ref ref, unsigned char color[3]);
+BSG_EXPORT extern void bsg_state_ref_light_specular_color(bsg_state_ref ref, unsigned char color[3]);
+BSG_EXPORT extern void bsg_state_ref_light_ambient_color(bsg_state_ref ref, unsigned char color[3]);
+BSG_EXPORT extern double bsg_state_ref_light_intensity(bsg_state_ref ref);
+BSG_EXPORT extern int bsg_state_ref_light_active(bsg_state_ref ref);
+BSG_EXPORT extern void bsg_state_ref_set_light(bsg_state_ref ref,
+					       int type,
+					       const point_t position,
+					       const vect_t direction,
+					       const unsigned char diffuse_color[3],
+					       const unsigned char specular_color[3],
+					       const unsigned char ambient_color[3],
+					       double intensity,
+					       int active);
+
+__END_DECLS
+
+#endif /* BSG_STATE_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/switch.h

@@ -0,0 +1,59 @@
+/*                        S W I T C H . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Public typed switch child-list and selection API.
+ */
+/** @{ */
+/* @file bsg/switch.h */
+
+#ifndef BSG_SWITCH_H
+#define BSG_SWITCH_H
+
+#include "common.h"
+#include "bsg/group.h"
+
+__BEGIN_DECLS
+
+#define BSG_SWITCH_NONE (-1)
+#define BSG_SWITCH_ALL  (-2)
+
+BSG_EXPORT extern size_t bsg_switch_ref_child_count(bsg_switch_ref ref);
+BSG_EXPORT extern bsg_node_ref bsg_switch_ref_child_at(bsg_switch_ref ref, size_t idx);
+BSG_EXPORT extern void bsg_switch_ref_append_child(bsg_switch_ref parent, bsg_node_ref child);
+BSG_EXPORT extern void bsg_switch_ref_remove_child(bsg_switch_ref parent, bsg_node_ref child);
+BSG_EXPORT extern void bsg_switch_ref_set_which_child(bsg_switch_ref ref, int which_child);
+BSG_EXPORT extern int bsg_switch_ref_which_child(bsg_switch_ref ref);
+
+__END_DECLS
+
+#endif /* BSG_SWITCH_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/tcl_data.h

@@ -0,0 +1,138 @@
+/*               B S G / T C L _ D A T A . H
+ * BRL-CAD
+ *
+ * Copyright (c) 1993-2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup bsg_tcl
+ *
+ * Tcl/legacy overlay data types.  Canonical home; bv/tcl_data.h is
+ * a backward-compatibility bridge.
+ */
+#ifndef BSG_TCL_DATA_H
+#define BSG_TCL_DATA_H
+
+#include "common.h"
+#include "bu/list.h"
+#include "bu/vls.h"
+#include "bu/ptbl.h"
+#include "bg/polygon_types.h"
+#include "bsg/faceplate.h"
+#include "vmath.h"
+
+/** @{ */
+/** @file bsg/tcl_data.h */
+
+#define BSG_POLY_CIRCLE_MODE 15
+#define BSG_POLY_CONTOUR_MODE 16
+
+/* DEPRECATED: display_list was the pre-BSG drawn-object grouping model.  Use
+ * semantic draw records and bsg_draw_intent (see bsg/draw_intent.h) instead.
+ * This struct will be removed in a future release. */
+struct display_list {
+    struct bu_list      l;
+    void               *dl_dp;                 /* Usually a struct directory * */
+    struct bu_vls       dl_path;
+    struct bu_list      dl_head_scene_obj;          /**< @brief  head of scene obj list for this group */
+    int                 dl_wflag;
+};
+
+struct bsg_data_axes_state {
+    int       draw;
+    int       color[3];
+    int       line_width;          /* in pixels */
+    fastf_t   size;                /* in view coordinates */
+    int       num_points;
+    point_t   *points;             /* in model coordinates */
+};
+
+struct bsg_data_arrow_state {
+    int       gdas_draw;
+    int       gdas_color[3];
+    int       gdas_line_width;          /* in pixels */
+    int       gdas_tip_length;
+    int       gdas_tip_width;
+    int       gdas_num_points;
+    point_t   *gdas_points;             /* in model coordinates */
+};
+
+struct bsg_data_label_state {
+    int         gdls_draw;
+    int         gdls_color[3];
+    int         gdls_num_labels;
+    int         gdls_size;
+    char        **gdls_labels;
+    point_t     *gdls_points;
+};
+
+struct bsg_data_line_state {
+    int       gdls_draw;
+    int       gdls_color[3];
+    int       gdls_line_width;          /* in pixels */
+    int       gdls_num_points;
+    point_t   *gdls_points;             /* in model coordinates */
+};
+
+typedef struct {
+    int                 gdps_draw;
+    int                 gdps_moveAll;
+    int                 gdps_color[3];
+    int                 gdps_line_width;        /* in pixels */
+    int                 gdps_line_style;
+    int                 gdps_cflag;             /* contour flag */
+    size_t              gdps_target_polygon_i;
+    size_t              gdps_curr_polygon_i;
+    size_t              gdps_curr_point_i;
+    point_t             gdps_prev_point;
+    bg_clip_t           gdps_clip_type;
+    fastf_t             gdps_scale;
+    point_t             gdps_origin;
+    mat_t               gdps_rotation;
+    mat_t               gdps_view2model;
+    mat_t               gdps_model2view;
+    struct bg_polygons  gdps_polygons;
+    fastf_t             gdps_data_vZ;
+} bsg_data_polygon_state;
+
+struct bsg_data_tclcad {
+    int           		gv_polygon_mode;  /* libtclcad polygon modes */
+    int		  		gv_hide;          /* libtclcad setting for hiding view - unused? */
+    fastf_t       		gv_data_vZ;
+    struct bsg_data_arrow_state	gv_data_arrows;
+    struct bsg_data_axes_state	gv_data_axes;
+    struct bsg_data_label_state	gv_data_labels;
+    struct bsg_data_line_state	gv_data_lines;
+    bsg_data_polygon_state	gv_data_polygons;
+    struct bsg_data_arrow_state	gv_sdata_arrows;
+    struct bsg_data_axes_state	gv_sdata_axes;
+    struct bsg_data_label_state	gv_sdata_labels;
+    struct bsg_data_line_state	gv_sdata_lines;
+    bsg_data_polygon_state	gv_sdata_polygons;
+    struct bsg_other_state	gv_prim_labels;
+};
+
+#endif /* BSG_TCL_DATA_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/util.h

@@ -0,0 +1,189 @@
+/*                         U T I L . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Scene-graph lifecycle and query utilities.
+ */
+/** @{ */
+/* @file bsg/util.h */
+
+#ifndef BSG_UTIL_H
+#define BSG_UTIL_H
+
+#include "common.h"
+#include "bu/hash.h"
+#include "bn/tol.h"
+#include "bsg/defines.h"
+#include "bsg/scene_builder.h"
+
+__BEGIN_DECLS
+
+/**
+ * Initialize a BSG view record.  BSG wrapper around
+ * bsg_init().  @p v must point to allocated but uninitialized storage.
+ * @p s is the optional view-set the view belongs to; pass NULL when unused.
+ */
+BSG_EXPORT extern void
+bsg_view_init(struct bsg_view *v, struct bsg_view_set *s);
+
+/**
+ * Initialize @p dest as a fresh BSG view and copy semantic view state from
+ * @p src.  Owned storage such as scene-object pools, callback recursion
+ * guards, view-state records, local settings records, and retained scene
+ * handles are newly initialized for @p dest rather than shared with @p src.
+ * @p s is the optional view-set the new view belongs to.
+ */
+BSG_EXPORT extern void
+bsg_view_init_copy(struct bsg_view *dest,
+		   const struct bsg_view *src,
+		   struct bsg_view_set *s);
+
+/**
+ * Free resources owned by a BSG view record.  BSG wrapper around bsg_free().
+ * Does not free the memory for @p v itself.
+ */
+BSG_EXPORT extern void
+bsg_view_free(struct bsg_view *v);
+
+/**
+ * Return the table of views registered in the view-set @p s.
+ * BSG-namespaced wrapper around bsg_set_views().
+ * Returns NULL when @p s is NULL.
+ */
+BSG_EXPORT extern struct bu_ptbl *
+bsg_set_views(struct bsg_view_set *s);
+
+__END_DECLS
+
+/* =========================================================================
+ * Legacy bv_* API declarations
+ *
+ * The following declarations were previously in bv/util.h.  bv/util.h is
+ * now a backward-compatibility bridge that includes this header.  All
+ * callers should migrate to bsg/util.h.  The bv_* names will be retired
+ * once the struct renames (bsg_view → bsg_view, etc.) are complete.
+ * ========================================================================= */
+
+__BEGIN_DECLS
+
+/* Set default values for a bv. */
+BSG_EXPORT extern void bsg_init(struct bsg_view *v, struct bsg_view_set *s);
+BSG_EXPORT extern void bsg_free(struct bsg_view *v);
+
+/* Zero-initialize a bsg_data_tclcad
+ * block. */
+BSG_EXPORT extern void bsg_data_tclcad_init(struct bsg_data_tclcad *d);
+BSG_EXPORT extern int bsg_view_is_independent(const struct bsg_view *v);
+BSG_EXPORT extern bsg_scene_ref bsg_view_independent_scope_ref(struct bsg_view *v, int create);
+BSG_EXPORT extern void bsg_view_independent_scope_destroy(struct bsg_view *v);
+
+BSG_EXPORT void bsg_mat_aet(struct bsg_view *v);
+
+#define BSG_AUTOVIEW_SCALE_DEFAULT -1
+BSG_EXPORT extern void bsg_autoview(struct bsg_view *v, fastf_t scale, int all_view_objs);
+BSG_EXPORT extern void bsg_autoview_bounds(struct bsg_view *v, fastf_t scale, const point_t min, const point_t max);
+
+/* Copy the size and camera info */
+BSG_EXPORT extern void bsg_sync(struct bsg_view *dest, struct bsg_view *src);
+
+/* Camera accessor functions */
+BSG_EXPORT extern fastf_t bsg_view_get_scale(const struct bsg_view *v);
+BSG_EXPORT extern void    bsg_view_set_scale(struct bsg_view *v, fastf_t scale);
+BSG_EXPORT extern fastf_t bsg_view_get_size(const struct bsg_view *v);
+BSG_EXPORT extern void    bsg_view_set_size(struct bsg_view *v, fastf_t size);
+BSG_EXPORT extern fastf_t bsg_view_get_perspective(const struct bsg_view *v);
+BSG_EXPORT extern void    bsg_view_set_perspective(struct bsg_view *v, fastf_t perspective);
+BSG_EXPORT extern void bsg_view_get_aet(const struct bsg_view *v, vect_t aet);
+BSG_EXPORT extern void bsg_view_set_aet(struct bsg_view *v, const vect_t aet);
+BSG_EXPORT extern void bsg_view_get_rotation(const struct bsg_view *v, mat_t rot);
+BSG_EXPORT extern void bsg_view_set_rotation(struct bsg_view *v, const mat_t rot);
+BSG_EXPORT extern void bsg_view_get_center_vec(const struct bsg_view *v, point_t center);
+BSG_EXPORT extern void bsg_view_set_center_vec(struct bsg_view *v, const point_t center);
+
+/* Copy settings common to views and shape nodes */
+BSG_EXPORT extern int bsg_appearance_settings_sync(struct bsg_appearance_settings *dest, const struct bsg_appearance_settings *src);
+
+/* Sync values within the bv, perform callbacks if any are defined */
+BSG_EXPORT extern void bsg_update(struct bsg_view *gvp);
+
+/* Update objects in the selection set (if any) and their children */
+BSG_EXPORT extern int bsg_update_selected(struct bsg_view *gvp);
+
+/* Clear or reset the knob states. */
+#ifndef BSG_KNOBS_ALL
+#define BSG_KNOBS_ALL 0
+#define BSG_KNOBS_RATE 1
+#define BSG_KNOBS_ABS 2
+#endif
+BSG_EXPORT extern void bsg_knobs_reset(struct bsg_view_knobs *k, int category);
+BSG_EXPORT extern unsigned long long bsg_knobs_hash(struct bsg_view_knobs *k, struct bu_data_hash_state *state);
+BSG_EXPORT extern int bsg_knobs_cmd_process(vect_t *rvec, int *do_rot, vect_t *tvec, int *do_tran, struct bsg_view *v, const char *cmd, fastf_t f, char origin, int model_flag, int incr_flag);
+BSG_EXPORT extern void bsg_knobs_rot(struct bsg_view *v, const vect_t rvec, char origin, char coords, const matp_t obj_rot, const pointp_t pvt_pt);
+BSG_EXPORT extern void bsg_knobs_tran(struct bsg_view *v, const vect_t tvec, int model_flag);
+BSG_EXPORT extern void bsg_update_rate_flags(struct bsg_view *v);
+
+/* Comparison and hash */
+BSG_EXPORT extern int bsg_differ(struct bsg_view *v1, struct bsg_view *v2);
+BSG_EXPORT extern unsigned long long bsg_hash(struct bsg_view *v);
+BSG_EXPORT extern size_t bsg_clear(struct bsg_view *v, int flags);
+
+/* Mouse/view coordinate utilities */
+#ifndef BSG_IDLE
+#define BSG_IDLE       0x000
+#define BSG_ROT        0x001
+#define BSG_TRANS      0x002
+#define BSG_SCALE      0x004
+#define BSG_CENTER     0x008
+#define BSG_CON_X      0x010
+#define BSG_CON_Y      0x020
+#define BSG_CON_Z      0x040
+#define BSG_CON_GRID   0x080
+#define BSG_CON_LINES  0x100
+#endif
+BSG_EXPORT extern int bsg_adjust(struct bsg_view *v, int dx, int dy, point_t keypoint, int mode, unsigned long long flags);
+BSG_EXPORT extern int bsg_screen_to_view(struct bsg_view *v, fastf_t *fx, fastf_t *fy, fastf_t x, fastf_t y);
+BSG_EXPORT extern int bsg_screen_pt(point_t *p, fastf_t x, fastf_t y, struct bsg_view *v);
+
+/* Object lookup */
+BSG_EXPORT void bsg_uniq_obj_name(struct bu_vls *oname, const char *seed, struct bsg_view *v);
+BSG_EXPORT int bsg_view_plane(plane_t *p, struct bsg_view *v);
+
+/* Environment variable controlled logging */
+#define BSG_ENABLE_ENV_LOGGING 1
+BSG_EXPORT void bsg_log(int level, const char *fmt, ...)  _BU_ATTR_PRINTF23;
+
+/* Debugging */
+BSG_EXPORT void bsg_view_print(const char *title, struct bsg_view *v, int verbosity);
+
+__END_DECLS
+
+#endif /* BSG_UTIL_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/view_scope.h

@@ -0,0 +1,67 @@
+/*                 V I E W _ S C O P E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * View-scope scene-ref API.
+ *
+ * A view-scope node is a container whose children are skipped during BSG
+ * render traversal for any view that does not match the node's owner metadata.
+ * When the owner is NULL the scope is "shared" and its children are visible
+ * to all views.
+ *
+ * Design:
+ *   - Per-view scope:  bsg_scene_view_scope_create(v, name) with v != NULL.
+ *                      Only the view v will see the children.
+ *   - Shared scope:    NULL owner metadata is supported by the traversal
+ *                      predicate; the NULL-owner allocation path is reserved
+ *                      for a future phase.
+ *
+ * Producers use view-scope nodes for per-view and shared view-local scene
+ * branches.
+ */
+/** @{ */
+/* @file bsg/view_scope.h */
+
+#ifndef BSG_VIEW_SCOPE_H
+#define BSG_VIEW_SCOPE_H
+
+#include "common.h"
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+/* Public callers create view scopes through bsg_scene_view_scope_create() in
+ * bsg/scene_builder.h and operate on opaque scene refs. */
+
+__END_DECLS
+
+#endif /* BSG_VIEW_SCOPE_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/view_set.h

@@ -1,4 +1,4 @@
-/*                      V I E W _ S E T S . H
+/*                      V I E W _ S E T . H
  * BRL-CAD
  *
  * Copyright (c) 1993-2026 United States Government as represented by
@@ -17,71 +17,73 @@
  * License along with this file; see the file named COPYING for more
  * information.
  */
-/** @addtogroup bv_util
+/** @addtogroup bsg_view_set
  *
  * In applications with multiple views, those views typically share common
  * scene objects and memory.  To manage this sharing, we define view sets.
+ *
+ * Canonical home; bv/view_sets.h is a backward-compatibility bridge.
  */
 /** @{ */
-/** @file bv/view_sets.h */
+/** @file bsg/view_set.h */
 
-#ifndef BV_VIEW_SETS_H
-#define BV_VIEW_SETS_H
+#ifndef BSG_VIEW_SET_H
+#define BSG_VIEW_SET_H
 
 #include "common.h"
-#include "bv/defines.h"
+#include "bsg/defines.h"
 
 __BEGIN_DECLS
 
 /**
  * Initialize an empty view set
  */
-BV_EXPORT void
-bv_set_init(struct bview_set *s);
+BSG_EXPORT void
+bsg_set_init(struct bsg_view_set *s);
 
 /**
  * Free view set
  */
-BV_EXPORT void
-bv_set_free(struct bview_set *s);
+BSG_EXPORT void
+bsg_set_free(struct bsg_view_set *s);
 
 /**
  * Add view v to set s, handling shared memory assignments.
  */
-BV_EXPORT void
-bv_set_add_view(struct bview_set *s, struct bview *v);
+BSG_EXPORT void
+bsg_set_add_view(struct bsg_view_set *s, struct bsg_view *v);
 
 /**
  * Remove view v from set s.  If v == NULL, all views
  * are removed from the set.
  */
-BV_EXPORT void
-bv_set_rm_view(struct bview_set *s, struct bview *v);
+BSG_EXPORT void
+bsg_set_rm_view(struct bsg_view_set *s, struct bsg_view *v);
 
 /**
  * Return a bu_ptbl holding pointers to all views in set s
  */
-BV_EXPORT struct bu_ptbl *
-bv_set_views(struct bview_set *s);
+BSG_EXPORT struct bu_ptbl *
+bsg_set_views(struct bsg_view_set *s);
 
 /**
  * Return a pointer to the view with name vname, if it is present in s.  If not
  * found, returns NULL
  */
-BV_EXPORT struct bview *
-bv_set_find_view(struct bview_set *s, const char *vname);
+BSG_EXPORT struct bsg_view *
+bsg_set_find_view(struct bsg_view_set *s, const char *vname);
 
 
-// Expose free_scene_obj for older codes - do not use in new coding
-BV_EXPORT struct bv_scene_obj *
-bv_set_fsos(struct bview_set *s);
+/* Opaque implementation recycling handle for draw contexts. */
+BSG_EXPORT void *
+bsg_set_fsos(struct bsg_view_set *s);
 
 
 __END_DECLS
 
 /** @} */
 
-#endif /* BV_VIEW_SETS_H */
+#endif /* BSG_VIEW_SET_H */
 
 /*
  * Local Variables:

include/bsg/view_state.h

@@ -0,0 +1,273 @@
+/*                  V I E W _ S T A T E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief Canonical command/UI view state accessors.
+ *
+ * A bsg_view_state is the semantic boundary between command/UI code and the
+ * internal runtime view caches.  Callers should edit camera, rendering,
+ * framebuffer, snapping, HUD/faceplate, and interaction records through this
+ * API rather than reaching into bsg_view storage directly.
+ */
+/** @{ */
+/* @file bsg/view_state.h */
+
+#ifndef BSG_VIEW_STATE_H
+#define BSG_VIEW_STATE_H
+
+#include "common.h"
+
+#include "bsg/defines.h"
+#include "bsg/camera.h"
+#include "bsg/render_settings.h"
+#include "bsg/snap_action.h"
+
+__BEGIN_DECLS
+
+struct bsg_view_state;
+
+#define BSG_VIEW_REFRESH_VIEW        0x00000001u
+#define BSG_VIEW_REFRESH_DRAW        0x00000002u
+#define BSG_VIEW_REFRESH_EDIT        0x00000004u
+#define BSG_VIEW_REFRESH_FRAMEBUFFER 0x00000008u
+#define BSG_VIEW_REFRESH_OVERLAY     0x00000010u
+#define BSG_VIEW_REFRESH_FORCE       0x80000000u
+#define BSG_VIEW_REFRESH_ALL         0xffffffffu
+
+struct bsg_view_refresh_state {
+    uint32_t dirty_flags;
+    uint64_t request_revision;
+    uint64_t completed_revision;
+    int suppress_depth;
+    int enabled;
+    int drawn_count;
+};
+
+BSG_EXPORT extern struct bsg_view_state *
+bsg_view_state_create(void);
+
+BSG_EXPORT extern void
+bsg_view_state_destroy(struct bsg_view_state *state);
+
+BSG_EXPORT extern struct bsg_view_state *
+bsg_view_state_active(struct bsg_view *v);
+
+BSG_EXPORT extern const struct bsg_view_state *
+bsg_view_state_active_const(const struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_state_sync_from_view(struct bsg_view_state *state, const struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_state_apply_to_view(const struct bsg_view_state *state, struct bsg_view *v);
+
+BSG_EXPORT extern struct bsg_camera *
+bsg_view_state_camera(struct bsg_view_state *state);
+
+BSG_EXPORT extern const struct bsg_camera *
+bsg_view_state_camera_const(const struct bsg_view_state *state);
+
+BSG_EXPORT extern struct bsg_render_settings *
+bsg_view_state_render_settings(struct bsg_view_state *state);
+
+BSG_EXPORT extern const struct bsg_render_settings *
+bsg_view_state_render_settings_const(const struct bsg_view_state *state);
+
+BSG_EXPORT extern int
+bsg_view_refresh_get(const struct bsg_view *v, struct bsg_view_refresh_state *record);
+
+BSG_EXPORT extern void
+bsg_view_refresh_set(struct bsg_view *v, const struct bsg_view_refresh_state *record);
+
+BSG_EXPORT extern void
+bsg_view_refresh_request(struct bsg_view *v, uint32_t flags);
+
+BSG_EXPORT extern int
+bsg_view_refresh_dirty(const struct bsg_view *v);
+
+BSG_EXPORT extern uint32_t
+bsg_view_refresh_consume(struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_refresh_complete(struct bsg_view *v);
+
+BSG_EXPORT extern int
+bsg_view_refresh_enabled(const struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_refresh_set_enabled(struct bsg_view *v, int enabled);
+
+BSG_EXPORT extern void
+bsg_view_refresh_suppress_begin(struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_refresh_suppress_end(struct bsg_view *v);
+
+BSG_EXPORT extern int
+bsg_view_refresh_suppressed(const struct bsg_view *v);
+
+BSG_EXPORT extern int
+bsg_view_refresh_drawn_count(const struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_refresh_set_drawn_count(struct bsg_view *v, int count);
+
+BSG_EXPORT extern struct bsg_selection *
+bsg_view_selection(struct bsg_view *v);
+
+BSG_EXPORT extern const struct bsg_selection *
+bsg_view_selection_const(const struct bsg_view *v);
+
+BSG_EXPORT extern int
+bsg_view_scene_attached(const struct bsg_view *v);
+
+BSG_EXPORT extern int
+bsg_view_scene_shared(const struct bsg_view *a, const struct bsg_view *b);
+
+BSG_EXPORT extern int
+bsg_view_adc_get(const struct bsg_view *v, struct bsg_adc_state *record);
+
+BSG_EXPORT extern void
+bsg_view_adc_set(struct bsg_view *v, const struct bsg_adc_state *record);
+
+BSG_EXPORT extern int
+bsg_view_center_dot_get(const struct bsg_view *v, struct bsg_other_state *record);
+
+BSG_EXPORT extern void
+bsg_view_center_dot_set(struct bsg_view *v, const struct bsg_other_state *record);
+
+BSG_EXPORT extern int
+bsg_view_grid_get(const struct bsg_view *v, struct bsg_grid_state *record);
+
+BSG_EXPORT extern void
+bsg_view_grid_set(struct bsg_view *v, const struct bsg_grid_state *record);
+
+BSG_EXPORT extern int
+bsg_view_model_axes_get(const struct bsg_view *v, struct bsg_axes *record);
+
+BSG_EXPORT extern void
+bsg_view_model_axes_set(struct bsg_view *v, const struct bsg_axes *record);
+
+BSG_EXPORT extern int
+bsg_view_view_axes_get(const struct bsg_view *v, struct bsg_axes *record);
+
+BSG_EXPORT extern void
+bsg_view_view_axes_set(struct bsg_view *v, const struct bsg_axes *record);
+
+BSG_EXPORT extern int
+bsg_view_scale_state_get(const struct bsg_view *v, struct bsg_other_state *record);
+
+BSG_EXPORT extern void
+bsg_view_scale_state_set(struct bsg_view *v, const struct bsg_other_state *record);
+
+BSG_EXPORT extern int
+bsg_view_params_get(const struct bsg_view *v, struct bsg_params_state *record);
+
+BSG_EXPORT extern void
+bsg_view_params_set(struct bsg_view *v, const struct bsg_params_state *record);
+
+BSG_EXPORT extern int
+bsg_view_interactive_rect_get(const struct bsg_view *v, struct bsg_interactive_rect_state *record);
+
+BSG_EXPORT extern void
+bsg_view_interactive_rect_set(struct bsg_view *v, const struct bsg_interactive_rect_state *record);
+
+BSG_EXPORT extern int
+bsg_view_settings_shared(const struct bsg_view *a, const struct bsg_view *b);
+
+BSG_EXPORT extern int
+bsg_view_framebuffer_mode(const struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_set_framebuffer_mode(struct bsg_view *v, int mode);
+
+BSG_EXPORT extern int
+bsg_view_cleared(const struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_set_cleared(struct bsg_view *v, int cleared);
+
+BSG_EXPORT extern int
+bsg_view_zclip(const struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_set_zclip(struct bsg_view *v, int zclip);
+
+BSG_EXPORT extern int
+bsg_view_lod_source_policy_get(const struct bsg_view *v,
+			       struct bsg_lod_source_policy_settings *policy);
+
+BSG_EXPORT extern void
+bsg_view_lod_source_policy_set(struct bsg_view *v,
+			       const struct bsg_lod_source_policy_settings *policy);
+
+BSG_EXPORT extern uint64_t
+bsg_view_frametime(const struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_set_frametime(struct bsg_view *v, uint64_t frametime);
+
+BSG_EXPORT extern int
+bsg_view_snap_lines(const struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_set_snap_lines(struct bsg_view *v, int enabled);
+
+BSG_EXPORT extern double
+bsg_view_snap_tolerance_factor(const struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_set_snap_tolerance_factor(struct bsg_view *v, double factor);
+
+BSG_EXPORT extern int
+bsg_view_snap_source_flags(const struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_set_snap_source_flags(struct bsg_view *v, int flags);
+
+BSG_EXPORT extern bsg_snap_kind_mask
+bsg_view_snap_kind_mask(const struct bsg_view *v);
+
+BSG_EXPORT extern bsg_snap_kind_mask
+bsg_view_prepare_tcl_snap(struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_snap_exclude_feature_clear(struct bsg_view *v);
+
+BSG_EXPORT extern void
+bsg_view_snap_exclude_feature_set(struct bsg_view *v, bsg_feature_ref ref);
+
+BSG_EXPORT extern int
+bsg_view_snap_exclude_feature_get(const struct bsg_view *v, bsg_feature_ref *ref);
+
+__END_DECLS
+
+#endif /* BSG_VIEW_STATE_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/visibility.h

@@ -1,7 +1,7 @@
-/*                           L O D . C P P
+/*                     V I S I B I L I T Y . H
  * BRL-CAD
  *
- * Copyright (c) 2013-2026 United States Government as represented by
+ * Copyright (c) 2026 United States Government as represented by
  * the U.S. Army Research Laboratory.
  *
  * This library is free software; you can redistribute it and/or
@@ -17,36 +17,34 @@
  * License along with this file; see the file named COPYING for more
  * information.
  */
-/** @file lod.c
- *
- * Level of Detail drawing configuration command.
+/** @addtogroup libbsg
  *
+ * @brief Visibility API boundary.
  */
+/** @{ */
+/* @file bsg/visibility.h */
+
+#ifndef BSG_VISIBILITY_H
+#define BSG_VISIBILITY_H
 
 #include "common.h"
+#include "bsg/defines.h"
 
-#include <stdlib.h>
-#include <ctype.h>
-#include <string.h>
+__BEGIN_DECLS
 
-#include "rt/geom.h"
+/* Raw-node visibility predicates are private traversal helpers. */
 
-#include "../ged_private.h"
+__END_DECLS
 
+#endif /* BSG_VISIBILITY_H */
 
-extern "C" int
-ged_lod2_core(struct ged *gedp, int UNUSED(argc), const char **UNUSED(argv))
-{
-    bu_vls_printf(gedp->ged_result_str, "New command modes enabled: use 'view lod' instead of 'lod'\n");
-    return BRLCAD_OK;
-}
-
-// Local Variables:
-// tab-width: 8
-// mode: C++
-// c-basic-offset: 4
-// indent-tabs-mode: t
-// c-file-style: "stroustrup"
-// End:
-// ex: shiftwidth=4 tabstop=8
-
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bsg/vlist.h

@@ -0,0 +1,248 @@
+/*                        V L I S T . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libbsg
+ *
+ * @brief
+ * Canonical vlist type, constants, macros and helpers for the BSG
+ * scene graph.
+ *
+ * This header is the authoritative definition of the vlist type.
+ * bv/vlist.h is a temporary backward-compatibility bridge that will be
+ * removed once all callers have migrated to bsg/vlist.h.
+ */
+/** @{ */
+/* @file bsg/vlist.h */
+
+#ifndef BSG_VLIST_H
+#define BSG_VLIST_H
+
+#include "common.h"
+#include <stdio.h>
+#include "vmath.h"
+#include "bu/magic.h"
+#include "bu/list.h"
+#include "bu/malloc.h"
+#include "bu/vls.h"
+#include "bsg/defines.h"
+
+__BEGIN_DECLS
+
+/* -----------------------------------------------------------------------
+ * Core vlist struct and type
+ * ----------------------------------------------------------------------- */
+
+#define BSG_VLIST_CHUNK 35   /**< @brief 32-bit mach => just less than 1k */
+
+struct bsg_vlist {
+    struct bu_list l;               /**< @brief magic, forw, back */
+    size_t nused;                   /**< @brief elements 0..nused active */
+    int cmd[BSG_VLIST_CHUNK];       /**< @brief BSG_VLIST_* command codes */
+    point_t pt[BSG_VLIST_CHUNK];    /**< @brief associated 3-point/vect */
+};
+typedef struct bsg_vlist bsg_vlist;
+
+#define BSG_VLIST_NULL  ((bsg_vlist *)0)
+#define BSG_VLIST_MAGIC 0x98237474
+#define BSG_CK_VLIST(_p) BU_CKMAG((_p), BSG_VLIST_MAGIC, "bsg_vlist")
+
+/* -----------------------------------------------------------------------
+ * Vlist command constants
+ * ----------------------------------------------------------------------- */
+#define BSG_VLIST_LINE_MOVE         0   /**< @brief specify new line */
+#define BSG_VLIST_LINE_DRAW         1   /**< @brief subsequent line vertex */
+#define BSG_VLIST_POLY_START        2   /**< @brief pt[] has surface normal */
+#define BSG_VLIST_POLY_MOVE         3   /**< @brief move to first poly vertex */
+#define BSG_VLIST_POLY_DRAW         4   /**< @brief subsequent poly vertex */
+#define BSG_VLIST_POLY_END          5   /**< @brief last vert (repeats 1st), draw poly */
+#define BSG_VLIST_POLY_VERTNORM     6   /**< @brief per-vertex normal */
+#define BSG_VLIST_TRI_START         7   /**< @brief pt[] has surface normal */
+#define BSG_VLIST_TRI_MOVE          8   /**< @brief move to first triangle vertex */
+#define BSG_VLIST_TRI_DRAW          9   /**< @brief subsequent triangle vertex */
+#define BSG_VLIST_TRI_END           10  /**< @brief last vert (repeats 1st), draw poly */
+#define BSG_VLIST_TRI_VERTNORM      11  /**< @brief per-vertex normal */
+#define BSG_VLIST_POINT_DRAW        12  /**< @brief Draw a single point */
+#define BSG_VLIST_POINT_SIZE        13  /**< @brief specify point pixel size */
+#define BSG_VLIST_LINE_WIDTH        14  /**< @brief specify line pixel width */
+#define BSG_VLIST_DISPLAY_MAT       15  /**< @brief specify the model matrix */
+#define BSG_VLIST_MODEL_MAT         16  /**< @brief specify the display matrix */
+#define BSG_VLIST_CMD_MAX           16  /**< @brief Max command number */
+
+/* -----------------------------------------------------------------------
+ * Vlist operation macros
+ *
+ * Applications must call BU_LIST_INIT on their free-list head before
+ * using BSG_GET_VLIST / BSG_ADD_VLIST.  These macros are non-PARALLEL.
+ * ----------------------------------------------------------------------- */
+
+#define BSG_GET_VLIST(_free_hd, p) do { \
+(p) = BU_LIST_FIRST(bsg_vlist, (_free_hd)); \
+if (BU_LIST_IS_HEAD((p), (_free_hd))) { \
+    BU_ALLOC((p), bsg_vlist); \
+    (p)->l.magic = BSG_VLIST_MAGIC; \
+} else { \
+    BU_LIST_DEQUEUE(&((p)->l)); \
+} \
+(p)->nused = 0; \
+    } while (0)
+
+/** Place an entire chain of bsg_vlist structs on the freelist _free_hd */
+#define BSG_FREE_VLIST(_free_hd, hd) do { \
+BU_CK_LIST_HEAD((hd)); \
+BU_LIST_APPEND_LIST((_free_hd), (hd)); \
+    } while (0)
+
+#define BSG_ADD_VLIST(_free_hd, _dest_hd, pnt, draw) do { \
+bsg_vlist *_vp; \
+BU_CK_LIST_HEAD(_dest_hd); \
+_vp = BU_LIST_LAST(bsg_vlist, (_dest_hd)); \
+if (BU_LIST_IS_HEAD(_vp, (_dest_hd)) || _vp->nused >= BSG_VLIST_CHUNK) { \
+    BSG_GET_VLIST(_free_hd, _vp); \
+    BU_LIST_INSERT((_dest_hd), &(_vp->l)); \
+} \
+VMOVE(_vp->pt[_vp->nused], (pnt)); \
+_vp->cmd[_vp->nused++] = (draw); \
+    } while (0)
+
+/** Change the transformation matrix to display */
+#define BSG_VLIST_SET_DISP_MAT(_free_hd, _dest_hd, _ref_pt) do { \
+bsg_vlist *_vp; \
+BU_CK_LIST_HEAD(_dest_hd); \
+_vp = BU_LIST_LAST(bsg_vlist, (_dest_hd)); \
+if (BU_LIST_IS_HEAD(_vp, (_dest_hd)) || _vp->nused >= BSG_VLIST_CHUNK) { \
+    BSG_GET_VLIST(_free_hd, _vp); \
+    BU_LIST_INSERT((_dest_hd), &(_vp->l)); \
+} \
+VMOVE(_vp->pt[_vp->nused], (_ref_pt)); \
+_vp->cmd[_vp->nused++] = BSG_VLIST_DISPLAY_MAT; \
+    } while (0)
+
+/** Change the transformation matrix to model */
+#define BSG_VLIST_SET_MODEL_MAT(_free_hd, _dest_hd) do { \
+bsg_vlist *_vp; \
+BU_CK_LIST_HEAD(_dest_hd); \
+_vp = BU_LIST_LAST(bsg_vlist, (_dest_hd)); \
+if (BU_LIST_IS_HEAD(_vp, (_dest_hd)) || _vp->nused >= BSG_VLIST_CHUNK) { \
+    BSG_GET_VLIST(_free_hd, _vp); \
+    BU_LIST_INSERT((_dest_hd), &(_vp->l)); \
+} \
+_vp->cmd[_vp->nused++] = BSG_VLIST_MODEL_MAT; \
+    } while (0)
+
+/** Set a point size to apply to vlist elements that follow */
+#define BSG_VLIST_SET_POINT_SIZE(_free_hd, _dest_hd, _size) do { \
+bsg_vlist *_vp; \
+BU_CK_LIST_HEAD(_dest_hd); \
+_vp = BU_LIST_LAST(bsg_vlist, (_dest_hd)); \
+if (BU_LIST_IS_HEAD(_vp, (_dest_hd)) || _vp->nused >= BSG_VLIST_CHUNK) { \
+    BSG_GET_VLIST(_free_hd, _vp); \
+    BU_LIST_INSERT((_dest_hd), &(_vp->l)); \
+} \
+_vp->pt[_vp->nused][0] = (_size); \
+_vp->cmd[_vp->nused++] = BSG_VLIST_POINT_SIZE; \
+    } while (0)
+
+/** Set a line width to apply to vlist elements that follow */
+#define BSG_VLIST_SET_LINE_WIDTH(_free_hd, _dest_hd, _width) do { \
+bsg_vlist *_vp; \
+BU_CK_LIST_HEAD(_dest_hd); \
+_vp = BU_LIST_LAST(bsg_vlist, (_dest_hd)); \
+if (BU_LIST_IS_HEAD(_vp, (_dest_hd)) || _vp->nused >= BSG_VLIST_CHUNK) { \
+    BSG_GET_VLIST(_free_hd, _vp); \
+    BU_LIST_INSERT((_dest_hd), &(_vp->l)); \
+} \
+_vp->pt[_vp->nused][0] = (_width); \
+_vp->cmd[_vp->nused++] = BSG_VLIST_LINE_WIDTH; \
+    } while (0)
+
+/* -----------------------------------------------------------------------
+ * BSG vlist API
+ * ----------------------------------------------------------------------- */
+
+/**
+ * Count the total number of vlist commands in @p vlist.
+ * Returns 0 when @p vlist is NULL.
+ */
+BSG_EXPORT extern size_t
+bsg_vlist_cmd_cnt(bsg_vlist *vlist);
+
+/**
+ * Duplicate the contents of a vlist.  The copy may be more densely
+ * packed than the source.
+ */
+BSG_EXPORT extern void
+bsg_vlist_copy(struct bu_list *vlists,
+               struct bu_list *dest,
+               const struct bu_list *src);
+
+/**
+ * Emit wireframe vlist commands for an ARB8 defined by the eight
+ * points @p pts into @p vhead, using @p vlfree as the free-list
+ * allocator.  Produces exactly 18 commands.
+ */
+BSG_EXPORT extern void
+bsg_vlist_arb8(struct bu_list *vhead, struct bu_list *vlfree, point_t pts[8]);
+
+/* -----------------------------------------------------------------------
+ * vlblock — colored vlist set
+ * ----------------------------------------------------------------------- */
+
+struct bsg_vlblock {
+    uint32_t magic;
+    size_t nused;
+    size_t max;
+    long *rgb;                      /**< @brief rgb[max] variable size array */
+    struct bu_list *head;           /**< @brief head[max] variable size array */
+    struct bu_list *free_vlist_hd;  /**< @brief where to get/put free vlists */
+};
+#define BSG_VLBLOCK_MAGIC 0x981bd112
+#define BSG_CK_VLBLOCK(_p) BU_CKMAG((_p), BSG_VLBLOCK_MAGIC, "bsg_vlblock")
+
+/* bsg_vlist_* and bsg_vlblock_* function declarations (still bv_ prefixed until rename slice) */
+BSG_EXPORT extern size_t bsg_vlist_cmd_cnt(bsg_vlist *vlist);
+BSG_EXPORT extern int bsg_vlist_bbox(struct bu_list *vlistp, point_t *bmin, point_t *bmax, size_t *length, int *dispmode);
+BSG_EXPORT extern void bsg_vlist_3string(struct bu_list *vhead, struct bu_list *free_hd, const char *string, const point_t origin, const mat_t rot, double scale);
+BSG_EXPORT extern void bsg_vlist_2string(struct bu_list *vhead, struct bu_list *free_hd, const char *string, double x, double y, double scale, double theta);
+BSG_EXPORT extern const char *bsg_vlist_get_cmd_description(int cmd);
+BSG_EXPORT extern size_t bsg_ck_vlist(const struct bu_list *vhead);
+BSG_EXPORT extern void bsg_vlist_copy(struct bu_list *vlists, struct bu_list *dest, const struct bu_list *src);
+BSG_EXPORT extern void bsg_vlist_export(struct bu_vls *vls, struct bu_list *hp, const char *name);
+BSG_EXPORT extern void bsg_vlist_import(struct bu_list *vlists, struct bu_list *hp, struct bu_vls *namevls, const unsigned char *buf);
+BSG_EXPORT extern void bsg_vlist_cleanup(struct bu_list *hd);
+BSG_EXPORT extern struct bsg_vlblock *bsg_vlblock_init(struct bu_list *free_vlist_hd, int max_ent);
+BSG_EXPORT extern void bsg_vlblock_free(struct bsg_vlblock *vbp);
+BSG_EXPORT extern struct bu_list *bsg_vlblock_find(struct bsg_vlblock *vbp, int r, int g, int b);
+BSG_EXPORT void bsg_vlist_rpp(struct bu_list *vlists, struct bu_list *hd, const point_t minn, const point_t maxx);
+BSG_EXPORT extern void bsg_plot_vlblock(FILE *fp, const struct bsg_vlblock *vbp);
+BSG_EXPORT extern void bsg_vlist_to_uplot(FILE *fp, const struct bu_list *vhead);
+
+__END_DECLS
+
+#endif /* BSG_VLIST_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/bu/opt.h

@@ -226,10 +226,170 @@ struct bu_opt_desc {
 BU_EXPORT extern int bu_opt_parse(struct bu_vls *msgs, size_t ac, const char **argv, const struct bu_opt_desc *ds);
 
 
+/** Machine readable option argument cardinality. */
+typedef enum {
+    BU_OPT_ARG_FLAG = 0,
+    BU_OPT_ARG_REQUIRED,
+    BU_OPT_ARG_OPTIONAL
+} bu_opt_arg_requirement_t;
+
+
+/** Machine readable option/operand value type hints. */
+typedef enum {
+    BU_OPT_VAL_UNKNOWN = 0,
+    BU_OPT_VAL_BOOL,
+    BU_OPT_VAL_INTEGER,
+    BU_OPT_VAL_NUMBER,
+    BU_OPT_VAL_VECTOR,
+    BU_OPT_VAL_COLOR,
+    BU_OPT_VAL_KEYWORD,
+    BU_OPT_VAL_STRING,
+    BU_OPT_VAL_DB_OBJECT,
+    BU_OPT_VAL_DB_PATH,
+    BU_OPT_VAL_FILE_PATH,
+    BU_OPT_VAL_RAW
+} bu_opt_value_type_t;
+
+
+/**
+ * Optional metadata for a bu_opt_desc entry.  Entries are matched to
+ * bu_opt_desc records by shortopt/longopt.  The array is terminated by
+ * BU_OPT_DESC_META_NULL.
+ */
+struct bu_opt_desc_meta {
+    const char *shortopt;
+    const char *longopt;
+    bu_opt_arg_requirement_t arg_requirement;
+    bu_opt_value_type_t arg_type;
+    int repeat;
+    const char * const *value_keywords;
+};
+
+
+#define BU_OPT_DESC_META_NULL {NULL, NULL, BU_OPT_ARG_FLAG, BU_OPT_VAL_UNKNOWN, 0, NULL}
+
+
+/** Optional positional operand metadata for a command. */
+struct bu_opt_operand_desc {
+    const char *name;
+    bu_opt_value_type_t type;
+    size_t min_count;
+    size_t max_count;
+    const char *help_string;
+    const char * const *value_keywords;
+};
+
+
+#define BU_OPT_OPERAND_DESC_NULL {NULL, BU_OPT_VAL_UNKNOWN, 0, 0, NULL, NULL}
+
+
+/** max_count value indicating that an operand may repeat without a fixed bound. */
+#define BU_OPT_COUNT_UNLIMITED ((size_t)-1)
+
+
+/** Command/subcommand schema for bu_opt metadata APIs. */
+struct bu_opt_cmd_desc {
+    const char *name;
+    const char *help_string;
+    const struct bu_opt_desc *options;
+    const struct bu_opt_desc_meta *option_meta;
+    const struct bu_opt_operand_desc *operands;
+    const struct bu_opt_cmd_desc *subcommands;
+};
+
+
+#define BU_OPT_CMD_DESC_NULL {NULL, NULL, NULL, NULL, NULL, NULL}
+
+
+/** Incremental validation result states. */
+typedef enum {
+    BU_OPT_VALIDATE_UNKNOWN = 0,
+    BU_OPT_VALIDATE_VALID,
+    BU_OPT_VALIDATE_INCOMPLETE,
+    BU_OPT_VALIDATE_INVALID
+} bu_opt_validate_state_t;
+
+
+/** Expected token classes for incremental validation. */
+typedef enum {
+    BU_OPT_EXPECT_NONE = 0,
+    BU_OPT_EXPECT_OPTION = 1,
+    BU_OPT_EXPECT_OPTION_ARG = 2,
+    BU_OPT_EXPECT_OPERAND = 4,
+    BU_OPT_EXPECT_SUBCOMMAND = 8
+} bu_opt_expected_t;
+
+
+/** Result container filled in by bu_opt_validate_* APIs. */
+struct bu_opt_validate_result {
+    bu_opt_validate_state_t state;
+    size_t token_start;
+    size_t token_end;
+    unsigned int expected;
+    const char *hint;
+    size_t completion_count;
+    const char **completion_candidates;
+    /**
+     * Dynamic completion type hint.  When completion_candidates is empty, this
+     * tells callers what kind of external completion source to query.  For
+     * example, BU_OPT_VAL_DB_OBJECT means the client should ask the geometry
+     * database for object names, BU_OPT_VAL_FILE_PATH means filesystem
+     * completion.  BU_OPT_VAL_UNKNOWN means static list candidates suffice or
+     * no completion hint is available.
+     */
+    bu_opt_value_type_t completion_type;
+    /**
+     * Byte offset of the token of interest in the original input string.
+     * Only populated by bu_opt_validate_string; zero otherwise.
+     */
+    size_t char_start;
+    /**
+     * Byte offset one past the end of the token of interest.
+     * Only populated by bu_opt_validate_string; zero otherwise.
+     */
+    size_t char_end;
+};
+
+
+#define BU_OPT_VALIDATE_RESULT_NULL {BU_OPT_VALIDATE_UNKNOWN, 0, 0, BU_OPT_EXPECT_NONE, NULL, 0, NULL, BU_OPT_VAL_UNKNOWN, 0, 0}
+
+
+/**
+ * Free any dynamically allocated completion-candidate data stored in a
+ * bu_opt_validate_result and reset it to the NULL initializer state.
+ */
+BU_EXPORT extern void bu_opt_validate_result_clear(struct bu_opt_validate_result *result);
+
+
+/**
+ * Generate a JSON command schema from optional side metadata and existing
+ * bu_opt_desc records.  The returned string must be released with bu_free.
+ */
+BU_EXPORT extern char *bu_opt_describe_json(const struct bu_opt_cmd_desc *cmd);
+
+
+/**
+ * Incrementally validate an argv array against a bu_opt command schema.
+ *
+ * @p cursor_arg identifies the token of interest; pass argc to validate the
+ * end-of-line position after the last argument.
+ */
+BU_EXPORT extern int bu_opt_validate_argv(const struct bu_opt_cmd_desc *cmd, size_t argc, const char **argv, size_t cursor_arg, struct bu_opt_validate_result *result);
+
+
+/**
+ * Incrementally validate a command string against a bu_opt command schema.
+ *
+ * @p cursor_pos identifies the character position of interest in @p input.
+ */
+BU_EXPORT extern int bu_opt_validate_string(const struct bu_opt_cmd_desc *cmd, const char *input, size_t cursor_pos, struct bu_opt_validate_result *result);
+
+
 /** Output format options for bu_opt documentation generation */
 typedef enum {
     BU_OPT_ASCII,
-    BU_OPT_DOCBOOK /* TODO */
+    BU_OPT_DOCBOOK, /* TODO */
+    BU_OPT_JSON
 } bu_opt_format_t;
 
 

include/bv/CMakeLists.txt

@@ -1,25 +0,0 @@
-set(
-  bv_headers
-  adc.h
-  defines.h
-  events.h
-  faceplate.h
-  lod.h
-  plot3.h
-  polygon.h
-  snap.h
-  tcl_data.h
-  util.h
-  vlist.h
-  view_sets.h
-)
-brlcad_manage_files(bv_headers ${INCLUDE_DIR}/brlcad/bv REQUIRED libbv)
-
-cmakefiles(CMakeLists.txt)
-
-# Local Variables:
-# tab-width: 8
-# mode: cmake
-# indent-tabs-mode: t
-# End:
-# ex: shiftwidth=2 tabstop=8

include/bv/defines.h

@@ -1,701 +0,0 @@
-/*                        B V I E W . H
- * BRL-CAD
- *
- * Copyright (c) 1993-2026 United States Government as represented by
- * the U.S. Army Research Laboratory.
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public License
- * version 2.1 as published by the Free Software Foundation.
- *
- * This library is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this file; see the file named COPYING for more
- * information.
- */
-/** @addtogroup bv_defines
- *
- * This header is intended to be independent of any one BRL-CAD library and is
- * specifically intended to allow the easy definition of common display list
- * types between otherwise independent libraries (libdm and libged, for
- * example).
- */
-
-#ifndef BV_DEFINES_H
-#define BV_DEFINES_H
-
-#include "common.h"
-#include "vmath.h"
-#include "bu/list.h"
-#include "bu/ptbl.h"
-#include "bu/vls.h"
-
-/** @{ */
-/** @file bv.h */
-
-#ifndef BV_EXPORT
-#  if defined(BV_DLL_EXPORTS) && defined(BV_DLL_IMPORTS)
-#    error "Only BV_DLL_EXPORTS or BV_DLL_IMPORTS can be defined, not both."
-#  elif defined(BV_DLL_EXPORTS)
-#    define BV_EXPORT COMPILER_DLLEXPORT
-#  elif defined(BV_DLL_IMPORTS)
-#    define BV_EXPORT COMPILER_DLLIMPORT
-#  else
-#    define BV_EXPORT
-#  endif
-#endif
-
-#include "bg/polygon_types.h"
-#include "bv/tcl_data.h"
-#include "bv/faceplate.h"
-
-__BEGIN_DECLS
-
-/* Define view ranges.  The numbers -2048 and 2047 go all the way back to the
- * original angle-distance cursor code that predates even BRL-CAD itself, but
- * (at least right now) there doesn't seem to be any documentation of why those
- * specific values were chosen. */
-#define BV_MAX 2047.0
-#define BV_MIN -2048.0
-#define BV_RANGE 4095.0
-/* Map +/-2048 BV space into -1.0..+1.0 :: x/2048*/
-#define INV_BV 0.00048828125
-#define INV_4096 0.000244140625
-
-
-#define BV_MINVIEWSIZE 0.0001
-#define BV_MINVIEWSCALE 0.00005
-
-#ifndef UP
-#  define UP 0
-#endif
-#ifndef DOWN
-#  define DOWN 1
-#endif
-
-#define BV_ANCHOR_AUTO          0
-#define BV_ANCHOR_BOTTOM_LEFT   1
-#define BV_ANCHOR_BOTTOM_CENTER 2
-#define BV_ANCHOR_BOTTOM_RIGHT  3
-#define BV_ANCHOR_MIDDLE_LEFT   4
-#define BV_ANCHOR_MIDDLE_CENTER 5
-#define BV_ANCHOR_MIDDLE_RIGHT  6
-#define BV_ANCHOR_TOP_LEFT      7
-#define BV_ANCHOR_TOP_CENTER    8
-#define BV_ANCHOR_TOP_RIGHT     9
-struct bv_label {
-    int           size;
-    struct bu_vls label;
-    point_t       p;         // 3D base of label text
-    int           line_flag; // If 1, draw a line from label anchor to target
-    point_t       target;
-    int           anchor;    // Either closest candidate to target (AUTO), or fixed
-    int           arrow;     // If 1, use an arrow indicating direction from label to target
-};
-
-
-/* Note - this container holds information both for data axes and for the more
- * elaborate visuals associated with the Archer style model axes.  The latter
- * is a superset of the former, so there should be no need for a separate data
- * type. */
-struct bv_axes {
-    int       draw;
-    point_t   axes_pos;             /* in model coordinates */
-    fastf_t   axes_size;            /* in view coordinates for HUD drawing-mode axes */
-    int       line_width;           /* in pixels */
-    int       axes_color[3];
-
-    /* The following are (currently) only used when drawing
-     * the faceplace HUD axes */
-    int       pos_only;
-    int       label_flag;
-    int       label_color[3];
-    int       triple_color;
-    int       tick_enabled;
-    int       tick_length;          /* in pixels */
-    int       tick_major_length;    /* in pixels */
-    fastf_t   tick_interval;        /* in mm */
-    int       ticks_per_major;
-    int       tick_threshold;
-    int       tick_color[3];
-    int       tick_major_color[3];
-};
-
-// Many settings have application level defaults that can be overridden for
-// individual scene objects.
-//
-// TODO - once this settles down, it will probably warrant a bu_structparse
-// for value setting
-struct bv_obj_settings {
-
-    int s_dmode;         	/**< @brief  draw modes (TODO - are these accurate?):
-				 *            0 - wireframe
-				 *	      1 - shaded bots and polysolids only (booleans NOT evaluated)
-				 *	      2 - shaded (booleans NOT evaluated)
-				 *	      3 - shaded (booleans evaluated)
-				 *	      4 - hidden line
-				 */
-    int mixed_modes;            /**< @brief  when drawing, don't remove an objects view objects for other modes */
-    fastf_t transparency;	/**< @brief  holds a transparency value in the range [0.0, 1.0] - 1 is opaque */
-
-    int color_override;
-    unsigned char color[3];	/**< @brief  color to draw as */
-
-    int s_line_width;		/**< @brief  current line width */
-    fastf_t s_arrow_tip_length; /**< @brief  arrow tip length */
-    fastf_t s_arrow_tip_width;  /**< @brief  arrow tip width */
-    int draw_solid_lines_only;   /**< @brief do not use dashed lines for subtraction solids */
-    int draw_non_subtract_only;  /**< @brief do not visualize subtraction solids */
-};
-#define BV_OBJ_SETTINGS_INIT {0, 0, 1.0, 0, {255, 0, 0}, 1, 0.0, 0.0, 0, 0}
-
-
-/* Note that it is possible for a view object to be view-only (not
- * corresponding directly to the wireframe of a database shape) but also based
- * off of database data.  Evaluated shaded objects would be an example, as
- * would NIRT solid shotline visualizations or overlap visualizations.  The
- * categorizations for the various types of bv_scene_obj objects would be:
- *
- * solid wireframe/triangles (obj.s):  BV_DBOBJ_BASED
- * rtcheck overlap visual:             BV_DBOBJ_BASED & BV_VIEWONLY
- * polygon/line/label:                 BV_VIEWONLY
- *
- * TODO - the distinction between view and db objs at this level probably needs
- * to go away - the application (or at least higher level libraries like
- * libged) should be the one managing the semantic meanings of objects.
- *
- * The distinction between objects (lines, labels, etc.) defined as
- * bv_scene_obj VIEW ONLY objects and the faceplate elements is objects defined
- * as bv_scene_obj objects DO exist in the 3D scene, and will move as 3D
- * elements when the view is manipulated (although label text is drawn parallel
- * to the view plane.)  Faceplate elements exist ONLY in the HUD and are not
- * managed as bv_scene_obj objects - they will not move with view manipulation.
- */
-#define BV_DBOBJ_BASED    0x01
-#define BV_VIEWONLY       0x02
-#define BV_LINES          0x04
-#define BV_LABELS         0x08
-#define BV_AXES           0x10
-#define BV_POLYGONS       0x20
-#define BV_MESH_LOD       0x40
-#define BV_CSG_LOD        0x80
-
-struct bview;
-
-#define BV_DB_OBJS 0x01
-#define BV_VIEW_OBJS 0x02
-#define BV_LOCAL_OBJS 0x04
-#define BV_CHILD_OBJS 0x08
-
-struct bv_scene_obj_internal;
-
-struct bv_scene_obj  {
-    struct bu_list l;
-
-    /* Internal implementation storage */
-    struct bv_scene_obj_internal *i;
-
-    /* View object name and type id */
-    unsigned long long s_type_flags;
-    struct bu_vls s_name;       /**< @brief object name (should be unique if view objects are to be addressed by name) */
-    void *s_path;       	/**< @brief alternative (app specific) encoding of s_name */
-    void *dp;       		/**< @brief app obj data */
-    mat_t s_mat;		/**< @brief mat to use for internal lookup and mesh LoD drawing */
-
-    /* Associated bv.  Note that scene objects are not assigned uniquely to
-     * one view.  This value may be changed by the application in a multi-view
-     * scenario as an object is edited from multiple different views, to supply
-     * the necessary view context for editing. If the object needs to retain
-     * knowledge of its original/creation view, it should save that info
-     * internally in its s_i_data container.
-     *
-     * BV_DEPRECATED: do not use s_v for view-policy control flow;
-     * scene data should not drive rendering decisions.  Use BViewState::redraw()
-     * or bv_view_get/set_* accessors instead. */
-    struct bview *s_v;
-
-    /* Knowledge of how to create/update s_vlist and the other 3D geometry data, as well as
-     * manage any custom data specific to this object */
-    void *s_i_data;  /**< @brief custom view data (bv_line_seg, bv_label, bv_polyon, etc) */
-
-    /* BV_DEPRECATED: LoD and CSG adaptive-wireframe update callbacks will be
-     * triggered by BViewState::redraw() rather than being registered here.
-     */
-    int (*s_update_callback)(struct bv_scene_obj *, struct bview *, int);  /**< @brief custom update/generator for s_vlist */
-    void (*s_free_callback)(struct bv_scene_obj *);  /**< @brief free any info stored in s_i_data, s_path and draw_data */
-
-    /* 3D vector list geometry data */
-    struct bu_list s_vlist;	/**< @brief  Pointer to unclipped vector list */
-    size_t s_vlen;			/**< @brief  Number of actual cmd[] entries in vlist */
-
-    /* Display lists accelerate drawing when we can use them */
-    unsigned int s_dlist;	/**< @brief  display list index */
-    int s_dlist_mode;		/**< @brief  drawing mode in which display list was generated (if it doesn't match s_os.s_dmode, dlist is out of date.) */
-    /* BV_DEPRECATED: replaced by dm_register_dlist_sensor / dm_fire_dlist_sensors
-     * in libdm.  Remains for backward compatibility; will be removed after one release cycle. */
-    int s_dlist_stale;		/**< @brief  set by client codes when dlist is out of date - dm must update. */
-    /* BV_DEPRECATED: dlist teardown is now handled via dm_register_dlist_sensor
-     * callbacks. */
-    void (*s_dlist_free_callback)(struct bv_scene_obj *);  /**< @brief free any dlist specific data */
-
-    /* 3D geometry metadata */
-    fastf_t s_size;		/**< @brief  Distance across solid, in model space */
-    fastf_t s_csize;		/**< @brief  Dist across clipped solid (model space) */
-    vect_t s_center;		/**< @brief  Center point of solid, in model space */
-    int s_displayobj;		/**< @brief  Vector list contains vertices in display context flag */
-    point_t bmin;
-    point_t bmax;
-    int have_bbox;
-
-    /* Display properties */
-    char s_flag;		/**< @brief  UP = object visible, DOWN = obj invis */
-    char s_iflag;	        /**< @brief  UP = illuminated, DOWN = regular */
-    int s_force_draw;           /**< @brief  1 = overrides s_flag and s_iflag - always draw (allows parents to force children to be visible) */
-    unsigned char s_color[3];	/**< @brief  color to draw as */
-    int s_soldash;		/**< @brief  solid/dashed line flag: 0 = solid, 1 = dashed*/
-    int s_arrow;		/**< @brief  arrow flag for view object drawing routines */
-    int s_changed;		/**< @brief  changed flag - set by s_update_callback if a change occurred */
-    int current;
-
-    /* Adaptive plotting info.
-     *
-     * The adaptive wireframe flag is set if the wireframe was created while
-     * adaptive mode is on - this is to allow reversion to non-adaptive
-     * wireframes if the mode is switched off without the view scale changing.
-     *
-     * NOTE: We store the following NOT for controlling the drawing, but so we
-     * can determine if the vlist is current with respect to the parent view
-     * settings.  These values SHOULD NOT be directly manipulated by any user
-     * facing commands (such as view obj).
-     *
-     * BV_DEPRECATED: adaptive_wireframe, view_scale, bot_threshold,
-     * curve_scale, and point_scale are snapshot values used to detect when a
-     * redraw is needed.  The owning decision logic is being moved to
-     * BViewState::redraw().
-     * These fields will be removed after one release cycle once BViewState
-     * owns the full redraw trigger. */
-    int     adaptive_wireframe;
-    int     csg_obj;
-    int     mesh_obj;
-    fastf_t view_scale;
-    size_t  bot_threshold;
-    fastf_t curve_scale;
-    fastf_t point_scale;
-
-    /* Scene object settings which also (potentially) have global defaults but
-     * may be overridden locally */
-    struct bv_obj_settings *s_os;
-    struct bv_obj_settings s_local_os;
-    int s_inherit_settings;           /**< @brief  Use current obj settings when drawing children instead of their settings */
-
-    /* Settings that may be less necessary... */
-    struct bv_scene_obj_old_settings s_old;
-
-    /* Child objects of this object */
-    struct bu_ptbl children;
-
-    /* Parent object of this object */
-    struct bv_scene_ob *parent;
-
-    /* Object level pointers to parent containers.  These are stored so
-     * that the object itself knows everything needed for data manipulation
-     * and it is unnecessary to explicitly pass other parameters. */
-
-    /* Reusable vlists */
-    struct bu_list *vlfree;
-
-    /* Container for reusing bv_scene_obj allocations */
-    struct bv_scene_obj *free_scene_obj;
-
-    /* View container containing this object */
-    struct bu_ptbl *otbl;
-
-    /* For more specialized routines not using vlists, we may need
-     * additional drawing data associated with a scene object */
-    void *draw_data;
-
-    /* User data to associate with this view object */
-    void *s_u_data;
-};
-
-
-
-/* bv_scene_groups (one level above scene objects, conceptually equivalent
- * to display_list) are used to capture the intent of drawing commands.  For
- * example, in the scenario where a draw command is used to visualize a comb
- * with sub-combs a and b:
- *
- * ged> draw comb
- *
- * The drawing code will check the proposed group against existing groups,
- * adding and removing accordingly.  It will then walk the hierarchy and create
- * bv_scene_obj instances for all solids below comb/a and comb/b as children
- * of the scene group.  Note that since we specified "comb" as the drawn
- * object, if comb/b is removed from comb and comb/c is added, we would expect
- * comb's displayed view to be updated to reflect its current structure.  If,
- * however, we instead did the original visualization with the commands:
- *
- * ged> draw comb/a
- * ged> draw comb/b
- *
- * The same solids would be drawn, but conceptually the comb itself is not
- * drawn - the two instances are.  If comb/b is removed and comb/c added, we
- * would not expect comb/c to be drawn since we never drew either that instance
- * or its parent comb.
- *
- * However, if comb/a and comb/b are drawn and then comb is drawn, the new comb
- * scene group will replace both the comb/a and comb/b groups since they are now
- * part of a higher level object being drawn.  If comb is drawn and comb/a is
- * subsequently drawn, it will be a no-op since "comb" is already covering that
- * case.
- *
- * The rule with bv_scene_group instances is their children must specify a
- * fully realized entity - if the s_name is "/comb/a" then everything below
- * /comb/a is drawn.  If /comb/a/obj1.s is erased, new bv_scene_group
- * entities will be needed to reflect the partial nature of /comb/a in the
- * visualization.  That requirement also propagates back up the tree. If a has
- * obj1.s and obj2.s below it, and /comb/a/obj1.s is erased, an original
- * "/comb" scene group will be replaced by new scene groups: /comb/a/obj2.s and
- * /comb/b.  Note that if /comb/a/obj1.s is subsequently drawn in isolation,
- * the scene groups will not collapse back to a single comb group - the user
- * will not at that point have explicitly issued instructions to draw comb as a
- * whole, even though all the individual elements have been drawn.  A "view
- * simplify" command should probably be added to support collapsing to the
- * simplest available option automatically in that situation.
- *
- * Note that the above rule is for explicit erasure from the drawn scene group
- * - if the structure of /comb/a is changed the drawn object is still "comb"
- * and the solid children of the existing group are updated to reflect the
- * current state of comb, rather than introducing new scene groups.
- *
- * Much like point_t and vect_t, the distinction between a group and an
- * individual object is largely semantic rather than a question of different
- * data storage.  A group just uses the bv_scene_obj container to store
- * group-wide default settings, and g.children holds the individual
- * bv_scene_obj entries corresponding to the solids.  A bv_scene_obj
- * should always map to a solid - a group may specify a solid but more
- * typically will reference the root of a CSG tree and have solids below it.
- * We define them to have different types only to help keep straight in the
- * code what is a conceptually a group and what is an individual scene object.
- *
- * TODO - once the latest drawing code update matures, the path management
- * done there should make the idea of a bv_scene_group moot.
- */
-#define bv_scene_group bv_scene_obj
-
-
-/* The primary "working" data for mesh Level-of-Detail (LoD) drawing is stored
- * in a bv_mesh_lod container.
- *
- * Most LoD information is deliberately hidden in the internal, but the key
- * data needed for drawing routines and view setup are exposed. Although this
- * data structure is primarily managed in libbg, the public data in this struct
- * is needed at many levels of the software stack, including libbv. */
-struct bv_mesh_lod {
-
-    // The set of triangle faces to be used when drawing
-    int fcnt;
-    const int *faces;
-
-    // The vertices used by the faces array
-    int pcnt;
-    const point_t *points;      // If using snapped points, that's this array.  Else, points == points_orig.
-    int porig_cnt;
-    const point_t *points_orig;
-
-    // Optional: per-face-vertex normals (one normal per triangle vertex - NOT
-    // one normal per vertex.  I.e., a given point from points_orig may have
-    // multiple normals associated with it in different faces.)
-    const vect_t *normals;
-
-    // Bounding box of the original full-detail data
-    point_t bmin;
-    point_t bmax;
-
-    // The scene object using this LoD structure
-    struct bv_scene_obj *s;
-
-    // Pointer to the higher level LoD context associated with this LoD data
-    void *c;
-
-    // Pointer to internal LoD implementation information specific to this object
-    void *i;
-};
-
-/* Flags to identify categories of objects to snap */
-#define BV_SNAP_SHARED 0x1
-#define BV_SNAP_LOCAL  0x2
-#define BV_SNAP_DB  0x4
-#define BV_SNAP_VIEW    0x8
-#define BV_SNAP_TCL    0x10
-
-/* We encapsulate non-camera settings into a container mainly to allow for
- * easier reuse of the same settings between different views - if a common
- * setting set is maintained between different views, this container allows
- * us to just point to the common set from all views using it. */
-struct bview_settings {
-    int            gv_snap_lines;
-    double 	   gv_snap_tol_factor;
-    struct bu_ptbl gv_snap_objs;
-    int		   gv_snap_flags;
-    int            gv_cleared;
-    int            gv_zclip;
-    int            gv_autoview;
-
-    // Adaptive plotting related settings - these are used when the wireframe
-    // generated by primitives is based on the view information.
-    int           adaptive_plot_mesh;
-    int           adaptive_plot_csg;
-    size_t        bot_threshold;
-    fastf_t       curve_scale;
-    fastf_t       point_scale;
-    int           redraw_on_zoom;
-    fastf_t 	  lod_scale;
-
-    // Faceplate elements fall into two general categories: those which are
-    // interactively adjusted (in a geometric sense) and those which are not.
-    // The non-interactive are generally just enabled or disabled:
-    struct bv_axes           gv_model_axes;
-    struct bv_axes           gv_view_axes;
-    struct bv_grid_state     gv_grid;
-    struct bv_other_state    gv_center_dot;
-    struct bv_params_state   gv_view_params;
-    struct bv_other_state    gv_view_scale;
-    double                   gv_frametime;
-
-    // Framebuffer visualization is possible if there is an attached dm and
-    // that dm has an associated framebuffer.  If those conditions are met,
-    // this variable is used to control how the fb is visualized.
-    int                      gv_fb_mode; // 0 = off, 1 = overlay, 2 = underlay
-
-    // More complex are the faceplate view elements not corresponding to
-    // geometry objects but editable by the user.  These aren't managed as
-    // gv_view_objs (they are HUD visuals and thus not part of the scene) so
-    // they have some unique requirements.
-    struct bv_adc_state              gv_adc;
-    struct bv_interactive_rect_state gv_rect;
-
-
-    // Not yet implemented - mechanism for defining a set of selected view
-    // objects
-    struct bu_ptbl                      *gv_selected;
-};
-
-/* A view needs to know what objects are active within it, but this is a
- * function not just of adding and removing objects via commands like
- * "draw" and "erase" but also what settings are active.  Shared objects
- * are common to multiple views, but if adaptive plotting is enabled the
- * scene objects cannot also be common - the representations of the objects
- * may be different in each view, even though the object list is shared.
- */
-struct bview_objs {
-
-    // Container for db object groups unique to this view (typical use case is
-    // adaptive plotting, where geometry wireframes may differ from view to
-    // view and thus need unique vlists.)
-    struct bu_ptbl  *db_objs;
-    // Container for storing bv_scene_obj elements unique to this view.
-    struct bu_ptbl  *view_objs;
-
-    // Available bv_vlist entities to recycle before allocating new for local
-    // view objects. This is used only if the app doesn't supply a vlfree -
-    // normally the app should do so, so memory from one view can be reused for
-    // other views.
-    struct bu_list  gv_vlfree;
-
-    /* Container for reusing bv_scene_obj allocations */
-    struct bv_scene_obj *free_scene_obj;
-};
-
-// Data for managing "knob" manipulation of views.  One historical hardware
-// example of this "knob" concept of view manipulation would be Dial boxes such
-// as the Silicon Graphics SN-921, used with 3D workstations in the early days.
-// Although we've not heard of Dial boxes being used with BRL-CAD in many
-// years, the mathematics of view manipulation used to support them still
-// underpins interactions driven with inputs from modern peripherals such as
-// the mouse.
-struct bview_knobs {
-
-    /* Rate data */
-    vect_t      rot_m;      // rotation - model coords
-    int         rot_m_flag;
-    char        origin_m;
-    void	*rot_m_udata;
-
-    vect_t	rot_o;      // rotation - object coords
-    int		rot_o_flag;
-    char	origin_o;
-    void	*rot_o_udata;
-
-    vect_t      rot_v;      // rotation - view coords
-    int         rot_v_flag;
-    char        origin_v;
-    void	*rot_v_udata;
-
-    fastf_t     sca;        // scale
-    int         sca_flag;
-    void	*sca_udata;
-
-    vect_t      tra_m;      // translation - model coords
-    int         tra_m_flag;
-    void	*tra_m_udata;
-
-    vect_t      tra_v;      // translation - view coords
-    int         tra_v_flag;
-    void	*tra_v_udata;
-
-    /* Absolute data */
-    vect_t      rot_m_abs;       // rotation - model coords
-    vect_t      rot_m_abs_last;
-
-    vect_t      rot_o_abs;       // rotation - object coords
-    vect_t      rot_o_abs_last;
-
-    vect_t      rot_v_abs;       // rotation - view coords
-    vect_t      rot_v_abs_last;
-
-    fastf_t     sca_abs;
-
-    vect_t      tra_m_abs;       // translation - model coords
-    vect_t      tra_m_abs_last;
-
-    vect_t      tra_v_abs;       // translation - view coords
-    vect_t      tra_v_abs_last;
-
-};
-
-struct bview_set;
-
-struct bview {
-    uint32_t	  magic;             /**< @brief magic number */
-    struct bu_vls gv_name;
-
-    /* Size info */
-    fastf_t       gv_i_scale;
-    fastf_t       gv_a_scale;        /**< @brief absolute scale */
-    fastf_t       gv_scale;
-    fastf_t       gv_size;           /**< @brief  2.0 * scale */
-    fastf_t       gv_isize;          /**< @brief  1.0 / size */
-    fastf_t       gv_base2local;
-    fastf_t       gv_local2base;
-    fastf_t       gv_rscale;
-    fastf_t       gv_sscale;
-
-    /* Information about current "window" into view.  This view may not be
-     * displayed (that's up to the display managers) and it is up to the
-     * calling code to set gv_width and gv_height to the current correct values
-     * for such a display, if it is associated with this view.  These
-     * definitions are needed in bview to support "view aware" algorithms that
-     * require information defining an active pixel "window" into the view. */
-    int		  gv_width;
-    int		  gv_height;
-    point2d_t	  gv_wmin; // view space bbox minimum of gv_width/gv_height window
-    point2d_t	  gv_wmax; // view space bbox maximum of gv_width/gv_height window
-
-    /* Camera info */
-    fastf_t       gv_perspective;    /**< @brief  perspective angle */
-    vect_t        gv_aet;
-    vect_t        gv_eye_pos;        /**< @brief  eye position */
-    vect_t        gv_keypoint;
-    char          gv_coord;          /**< @brief  coordinate system */
-    char          gv_rotate_about;   /**< @brief  indicates what point rotations are about */
-    mat_t         gv_rotation;
-    mat_t         gv_center;
-    mat_t         gv_model2view;
-    mat_t         gv_pmodel2view;
-    mat_t         gv_view2model;
-    mat_t         gv_pmat;           /**< @brief  perspective matrix */
-
-    /* Keyboard/mouse info */
-    fastf_t       gv_prevMouseX;
-    fastf_t       gv_prevMouseY;
-    int           gv_mouse_x;
-    int           gv_mouse_y;
-    point_t       gv_prev_point;
-    point_t       gv_point;
-    char          gv_key;
-    unsigned long gv_mod_flags;
-    fastf_t       gv_minMouseDelta;
-    fastf_t       gv_maxMouseDelta;
-
-    /* Settings */
-    struct bview_settings *gv_s;     /**< @brief shared settings supplied by user */
-    struct bview_settings gv_ls;     /**< @brief locally maintained settings specific to view (used if gv_s is null) */
-
-    /* If a view is marked as independent, its local containers are used even
-     * if pointers to shared tables are set. This allows for fully independent
-     * views with the same GED instance, at the cost of increased memory usage
-     * if multiple views draw the same objects. */
-    int independent;
-
-    /* Set containing this view.  Also holds pointers to resources shared
-     * across multiple views */
-    struct bview_set *vset;
-
-    /* Scene objects active in a view.  Managing these is a relatively complex
-     * topic and depends on whether a view is shared, independent or adaptive.
-     * Shared objects are common across views to make more efficient use of
-     * system memory. */
-    struct bview_objs gv_objs;
-
-    /* We sometimes need to define the volume in space that is "active" for the
-     * view.  For an orthogonal camera this is the oriented bounding box
-     * extruded to contain active scene objects visible in the view  The app
-     * must set the gv_bounds_update callback to bg_view_bound so a bv_update
-     * call can update these values.*/
-    point_t obb_center;
-    vect_t obb_extent1;
-    vect_t obb_extent2;
-    vect_t obb_extent3;
-    void (*gv_bounds_update)(struct bview *);
-
-    /* "Backed out" point, lookat direction, scene radius. Used for geometric
-     * view based interrogation. */
-    point_t gv_vc_backout;
-    vect_t gv_lookat;
-    double radius;
-
-    /* Knob-based view manipulation data */
-    struct bview_knobs k;
-
-    /* Virtual trackball position */
-    point_t     orig_pos;
-
-    // libtclcad data
-    struct bv_data_tclcad gv_tcl;
-
-    /* Callback, external data */
-    void          (*gv_callback)(struct bview *, void *);  /**< @brief  called in ged_view_update with gvp and gv_clientData */
-    void           *gv_clientData;   /**< @brief  passed to gv_callback */
-    struct bu_ptbl *callbacks;
-    void           *dmp;             /* Display manager pointer, if one is associated with this view */
-    void           *u_data;          /* Caller data associated with this view */
-};
-
-// Because bview instances frequently share objects in applications, they are
-// not always fully independent - we define a container and some basic
-// operations to manage this.
-struct bview_set_internal;
-struct bview_set {
-    struct bview_set_internal   *i;
-    struct bview_settings       settings;
-};
-
-__END_DECLS
-
-#endif /* BV_DEFINES_H */
-
-/** @} */
-/*
- * Local Variables:
- * mode: C
- * tab-width: 8
- * indent-tabs-mode: t
- * c-file-style: "stroustrup"
- * End:
- * ex: shiftwidth=4 tabstop=8
- */

include/bv/events.h

@@ -1,59 +0,0 @@
-/*                        E V E N T S . H
- * BRL-CAD
- *
- * Copyright (c) 2021-2026 United States Government as represented by
- * the U.S. Army Research Laboratory.
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public License
- * version 2.1 as published by the Free Software Foundation.
- *
- * This library is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this file; see the file named COPYING for more
- * information.
- */
-/** @file events.h
- *
- * View objects may define their behaviors in response to events (key
- * presses, mouse movements, etc.).  Because such events are defined
- * on a per-environment basis, we need to define a common language to
- * express responses to those events in order to avoid dependence on
- * that environment.
- *
- * The calling code is responsible for translating the environment
- * specific events into bv events.
- *
- * TODO - eventually these should probably be augmented by common purpose
- * specific options (i.e. define a BV_X_CONSTRAIN so the calling application
- * can map either x or X to the enabling of that particular motion constraint
- * during editing, for example...)  However, I think we'll also need to pass
- * the lower level info as there are too many purpose specific possibilities
- * to encode them all up front.
- */
-
-#define BV_KEY_PRESS            0x001
-#define BV_KEY_RELEASE          0x002
-#define BV_LEFT_MOUSE_PRESS     0x004
-#define BV_LEFT_MOUSE_RELEASE   0x008
-#define BV_RIGHT_MOUSE_PRESS    0x010
-#define BV_RIGHT_MOUSE_RELEASE  0x020
-#define BV_MIDDLE_MOUSE_PRESS   0x040
-#define BV_MIDDLE_MOUSE_RELEASE 0x080
-#define BV_CTRL_MOD             0x100
-#define BV_SHIFT_MOD            0x200
-#define BV_ALT_MOD              0x400
-
-/*
- * Local Variables:
- * tab-width: 8
- * mode: C
- * indent-tabs-mode: t
- * c-file-style: "stroustrup"
- * End:
- * ex: shiftwidth=4 tabstop=8
- */

include/bv/lod.h

@@ -1,236 +0,0 @@
-/*                            L O D . H
- * BRL-CAD
- *
- * Copyright (c) 2004-2026 United States Government as represented by
- * the U.S. Army Research Laboratory.
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public License
- * version 2.1 as published by the Free Software Foundation.
- *
- * This library is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this file; see the file named COPYING for more
- * information.
- */
-
-/*----------------------------------------------------------------------*/
-/** @addtogroup bv_lod
- *
- *  @brief
- *  Functions for generating view dependent level-of-detail data,
- *  particularly for meshes.
- */
-/** @{ */
-/* @file lod.h */
-
-#ifndef BV_LOD_H
-#define BV_LOD_H
-
-#include "common.h"
-#include "vmath.h"
-#include "bu/ptbl.h"
-#include "bv/defines.h"
-
-__BEGIN_DECLS
-
-/* Given a view, construct either an oriented bounding box or a view frustum
- * extruded to contain scene objects visible in the view.  Conceptually, think
- * of it as a framebuffer pane pushed through the scene in the direction the
- * camera is looking.  If the view width and height are not set or there is
- * some other problem, no volume is computed. This function is intended
- * primarily to be set as an updating callback for the bview structure. */
-BV_EXPORT extern void
-bv_view_bounds(struct bview *v);
-
-/* Given a screen x,y coordinate, construct the set of all scene objects whose
- * AABB intersect with the OBB created by the projection of that pixel through
- * the scene. sset holds the struct bv_scene_obj pointers of the selected
- * objects.  */
-BV_EXPORT int
-bv_view_objs_select(struct bu_ptbl *sset, struct bview *v, int x, int y);
-
-/* Given a screen x1,y1,x2,y2 rectangle, construct and return the set of all scene
- * objects whose AABB intersect with the OBB created by the projection of that
- * rectangle through the scene. */
-BV_EXPORT int
-bv_view_objs_rect_select(struct bu_ptbl *sset, struct bview *v, int x1, int y1, int x2, int y2);
-
-/* Storing and reading from a lot of small, individual files doesn't work very
- * well on some platforms.  We provide a "context" to manage bookkeeping of data
- * across objects. The details are implementation internal - the application
- * will simply create a context with a file name and provide it to the various
- * LoD calls. */
-struct bv_mesh_lod_context_internal;
-struct bv_mesh_lod_context {
-    struct bv_mesh_lod_context_internal *i;
-};
-
-/* Create an LoD context using "name". If data is already present associated
- * with that name it will be loaded, otherwise a new storage structure will be
- * initialized.  If creation or loading fails for any reason the return value
- * NULL.
- *
- * Note that "name" should be a full, unique path associated with the source
- * database.  libbu will manage where the context data is cached.
-*/
-BV_EXPORT struct bv_mesh_lod_context *
-bv_mesh_lod_context_create(const char *name);
-
-/* Free all memory associated with context c.  Note that this call does NOT
- * remove the on-disk data. */
-BV_EXPORT void
-bv_mesh_lod_context_destroy(struct bv_mesh_lod_context *c);
-
-/* Remove cache data associated with key.  If key == 0, remove ALL cache data
- * associated with all LoD objects in c. (i.e. a full LoD cache reset for that
- * .g database).  If key == 0 AND c == NULL, clear all LoD cache data for all
- * .g databases associated with the current user's cache.
- */
-BV_EXPORT void
-bv_mesh_lod_clear_cache(struct bv_mesh_lod_context *c, unsigned long long key);
-
-/**
- * Given a set of points and faces, calculate a lookup key and determine if the
- * cache has the LoD data for this particular mesh.  If it does not, do the
- * initial calculations to generate the cached LoD data needed for subsequent
- * lookups, otherwise just return the calculated key.
- *
- * This is potentially an expensive operation, particularly if the LoD data set
- * must be generated for the mesh.
- *
- * If user_key != 0, it will be used instead of the mesh data hash as the db
- * key to be used for subsequent lookups.  Typically calculated with
- * bu_data_hash from user supplied data, if the mesh data is not
- * the desired source of the key.
- *
- * Note: to clear pre-existing cached data, run bv_mesh_lod_clear_cache();
- *
- * @return the lookup key calculated from the data */
-BV_EXPORT 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);
-
-
-/**
- * Given a name, see if the context has a key associated with that name.
- * If so return it, else return zero.
- *
- * Users of this feature need to be aware that it is the responsibility
- * of the application to maintain the LoD cache data and keep it current -
- * it is quite possible, in a data sense, for the LoD data to be out of
- * date if something has changed the named geometry object and not updated
- * the cache.
- *
- * The advantage of this feature, if the application does maintain the
- * data correctly, is to make it possible to load a high level view of
- * a large model without having to hash the full mesh data of the model
- * to retrieve the data.
- */
-BV_EXPORT unsigned long long
-bv_mesh_lod_key_get(struct bv_mesh_lod_context *c, const char *name);
-
-/**
- * Given a name and a key, instruct the context to associate that name with
- * the key.
- *
- * Returns 0 if successful, else error
- */
-BV_EXPORT int
-bv_mesh_lod_key_put(struct bv_mesh_lod_context *c, const char *name, unsigned long long key);
-
-/**
- * Set up the bv_mesh_lod container using cached LoD information associated
- * with key.  If no cached data has been prepared, a NULL container is
- * returned - to prepare cached data, call bv_mesh_lod_cache with the original
- * mesh input data.  This call is intended to be usable in situations where
- * we don't want to pull the full mesh data set into memory, so we can't assume
- * the original data is present.
- *
- * Note: bv_mesh_lod assumes a non-changing mesh - if the mesh is changed after
- * it is created, the internal container does *NOT* automatically update.  In
- * that case the old struct should be destroyed and a new one created.
- *
- * A bv_mesh_lod return from this function will be initialized only to the
- * lowest level of data (i.e. the coarsest possible representation of the
- * object.) To tailor the data, use the bv_mesh_lod_view function.  For lower
- * level control, the bv_mesh_lod_level function may be used to explicitly
- * manipulate the loaded LoD (usually used for debugging, but also useful if an
- * application wishes to visualize levels explicitly.)
- */
-BV_EXPORT struct bv_mesh_lod *
-bv_mesh_lod_create(struct bv_mesh_lod_context *c, unsigned long long key);
-
-/* Clean up the lod container. */
-BV_EXPORT void
-bv_mesh_lod_destroy(struct bv_mesh_lod *l);
-
-/**
- * Given a scene object with mesh LoD data stored in s->draw_data, reduce
- * memory footprint (for use after client codes have completed use of a
- * particular level's info, but aren't done with the object.  Main use case
- * currently is OpenGL display lists - once generated, we can clear the
- * internally stored LoD data until the level changes.  Note that there is a
- * re-loading performance penalty as a trade-off to the memory savings. */
-BV_EXPORT void
-bv_mesh_lod_memshrink(struct bv_scene_obj *s);
-
-/**
- * Given a scene object with mesh LoD data stored in s->draw_data and a bview,
- * load the appropriate level of detail for displaying the mesh in that view.
- * Set reset == 1 if the caller wants to undo a memshrink operation even if the
- * level isn't changed by the current view settings.
- *
- * Returns the level selected.  If v == NULL, return current level of l.  If
- * there is an error or l == NULL, return -1; */
-BV_EXPORT int
-bv_mesh_lod_view(struct bv_scene_obj *s, struct bview *v, int reset);
-
-/**
- * Given a scene object with mesh LoD data stored in s->draw_data and a detail
- * level, load the appropriate data.  This is not normally used by client codes
- * directly, but may be needed if an app needs  manipulate the level of detail
- * without a view.  Set reset == 1 if the caller wants to undo a memshrink
- * operation even if the level isn't changed by the current view settings.
- *
- * Returns the level selected.  If level == -1, return current level of l.  If
- * there is an error, return -1; */
-BV_EXPORT int
-bv_mesh_lod_level(struct bv_scene_obj *s, int level, int reset);
-
-/* Free a scene object's LoD data.  Suitable as a s_free_callback function
- * for a bv_scene_obj.  This function will also trigger any additional
- * "free" callback functions which might be defined for the LoD container. */
-BV_EXPORT void
-bv_mesh_lod_free(struct bv_scene_obj *s);
-
-
-
-/* In order to preserve library barriers, a number of operations needed to
- * realize LoD drawing are defined at other library layers and made available
- * to the core LoD management logic with callbacks */
-
-/* Set function callbacks for retrieving and freeing high levels of mesh detail */
-BV_EXPORT void
-bv_mesh_lod_detail_setup_clbk(struct bv_mesh_lod *lod, int (*clbk)(struct bv_mesh_lod *, void *), void *cb_data);
-BV_EXPORT void
-bv_mesh_lod_detail_clear_clbk(struct bv_mesh_lod *lod, int (*clbk)(struct bv_mesh_lod *, void *));
-BV_EXPORT void
-bv_mesh_lod_detail_free_clbk(struct bv_mesh_lod *lod, int (*clbk)(struct bv_mesh_lod *, void *));
-
-__END_DECLS
-
-#endif  /* BV_LOD_H */
-/** @} */
-/*
- * Local Variables:
- * mode: C
- * tab-width: 8
- * indent-tabs-mode: t
- * c-file-style: "stroustrup"
- * End:
- * ex: shiftwidth=4 tabstop=8
- */

include/bv/polygon.h

@@ -1,140 +0,0 @@
-/*                        P O L Y G O N . H
- * BRL-CAD
- *
- * Copyright (c) 2004-2026 United States Government as represented by
- * the U.S. Army Research Laboratory.
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public License
- * version 2.1 as published by the Free Software Foundation.
- *
- * This library is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this file; see the file named COPYING for more
- * information.
- */
-
-/*----------------------------------------------------------------------*/
-/** @addtogroup bv_polygon
- *
- *  @brief Functions for working with polygons
- */
-/* @file polygon.h */
-/** @{ */
-
-#ifndef BV_POLYGON_H
-#define BV_POLYGON_H
-
-#include "common.h"
-#include "vmath.h"
-#include "bu/color.h"
-#include "bv/defines.h"
-#include "bg/polygon.h"
-#include "bg/polygon_types.h"
-
-__BEGIN_DECLS
-
-/* View polygon logic and types */
-
-#define BV_POLYGON_GENERAL 0
-#define BV_POLYGON_CIRCLE 1
-#define BV_POLYGON_ELLIPSE 2
-#define BV_POLYGON_RECTANGLE 3
-#define BV_POLYGON_SQUARE 4
-
-struct bv_polygon {
-    int                 type;
-    int                 fill_flag;         /* set to shade the interior */
-    vect2d_t            fill_dir;
-    fastf_t             fill_delta;
-    struct bu_color     fill_color;
-    long                curr_contour_i;
-    long                curr_point_i;
-    point_t             origin_point;      /* For non-general polygons  */
-
-    /* We stash the view plane creation, so we know how to return
-     * to it for future 2D alterations */
-    plane_t             vp;
-
-    /* Offset of polygon plane from the view plane.  Allows for moving
-     * the polygon "towards" and "away from" the viewer. */
-    fastf_t vZ;
-
-    /* Actual polygon info */
-    struct bg_polygon polygon;
-
-    /* Arbitrary data */
-    void *u_data;
-};
-
-// Given a polygon, create a scene object
-BV_EXPORT extern struct bv_scene_obj *bv_create_polygon_obj(struct bview *v, int flags, struct bv_polygon *p);
-
-// Creates a scene object with a default polygon
-BV_EXPORT extern struct bv_scene_obj *bv_create_polygon(struct bview *v, int flags, int type, point_t *fp);
-
-// Various update modes have similar logic - we pass in the flags to the update
-// routine to enable/disable specific portions of the overall flow.
-#define BV_POLYGON_UPDATE_DEFAULT 0
-#define BV_POLYGON_UPDATE_PROPS_ONLY 1
-#define BV_POLYGON_UPDATE_PT_SELECT 2
-#define BV_POLYGON_UPDATE_PT_SELECT_CLEAR 3
-#define BV_POLYGON_UPDATE_PT_MOVE 4
-#define BV_POLYGON_UPDATE_PT_APPEND 5
-BV_EXPORT extern int bv_update_polygon(struct bv_scene_obj *s, struct bview *v, int utype);
-
-// Update just the scene obj vlist, without altering the source polygon
-BV_EXPORT extern void bv_polygon_vlist(struct bv_scene_obj *s);
-
-// Find the closest polygon obj to a point
-BV_EXPORT extern struct bv_scene_obj *bv_select_polygon(struct bu_ptbl *objs, point_t *cp);
-
-BV_EXPORT extern int bv_move_polygon(struct bv_scene_obj *s, point_t *cp, point_t *pp);
-BV_EXPORT extern struct bv_scene_obj *bv_dup_view_polygon(const char *nname, struct bv_scene_obj *s);
-
-// Copy a bv polygon.  Note that this also performs a
-// view sync - if the user is copying the polygon into
-// another view, they will have to update the output's
-// bview to match their target view.
-BV_EXPORT extern void bv_polygon_cpy(struct bv_polygon *dest , struct bv_polygon *src);
-
-// Calculate a suggested default fill delta based on the polygon structure.  The
-// idea is to try and strike a balance between line count and having enough fill
-// lines to highlight interior holes.
-BV_EXPORT extern int bv_polygon_calc_fdelta(struct bv_polygon *p);
-
-BV_EXPORT extern struct bg_polygon *
-bv_polygon_fill_segments(struct bg_polygon *poly, plane_t *vp, vect2d_t line_slope, fastf_t line_spacing);
-
-// For all polygon bv_scene_objs in the objs table, apply the specified boolean
-// op using p and replace the original polygon geometry in objs with the
-// results (NOTE:  p will not act on itself if it is in objs):
-//
-// u : objs[i] u p  (unions p with objs[i])
-// - : objs[i] - p  (removes p from objs[i])
-// + : objs[i] + p  (intersects p with objs[i])
-//
-// At a data structure level, what happens is the bv_polygon geometry stored in
-// the bv_polygon stored as the data entry for a bv_scene_obj is replaced.  The
-// bv_scene_obj and bv_polygon pointers should remain valid, but the bv_polygon
-// contained in bv_polygon is replaced - calling code should not rely on the
-// bv_polygon pointer remaining the same after a boolean operation.
-BV_EXPORT extern int bv_polygon_csg(struct bv_scene_obj *target, struct bv_scene_obj *stencil, bg_clip_t op);
-
-__END_DECLS
-
-#endif  /* BV_POLYGON_H */
-/** @} */
-/*
- * Local Variables:
- * mode: C
- * tab-width: 8
- * indent-tabs-mode: t
- * c-file-style: "stroustrup"
- * End:
- * ex: shiftwidth=4 tabstop=8
- */

include/bv/tcl_data.h

@@ -1,171 +0,0 @@
-/*                     B V I E W / T C L _ D A T A . H
- * BRL-CAD
- *
- * Copyright (c) 1993-2026 United States Government as represented by
- * the U.S. Army Research Laboratory.
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public License
- * version 2.1 as published by the Free Software Foundation.
- *
- * This library is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this file; see the file named COPYING for more
- * information.
- */
-/** @addtogroup bv_tcl
- *
- * We're retaining these for libtclcad - don't use elsewhere
- */
-#ifndef DM_BV_TCL_DATA_H
-#define DM_BV_TCL_DATA_H
-
-#include "common.h"
-#include "bu/list.h"
-#include "bu/vls.h"
-#include "bu/ptbl.h"
-#include "bg/polygon_types.h"
-#include "bv/faceplate.h"
-#include "vmath.h"
-
-/** @{ */
-/** @file bv/tcl_data.h */
-
-#define BV_POLY_CIRCLE_MODE 15
-#define BV_POLY_CONTOUR_MODE 16
-
-// Separate these out, as we'll try not to use them in the new display work
-struct bv_scene_obj_old_settings {
-    char s_wflag;		/**< @brief  work flag - used by various libged and Tcl functions */
-    char s_dflag;		/**< @brief  1 - s_basecolor is derived from the default */
-    unsigned char s_basecolor[3];	/**< @brief  color from containing region */
-    char s_uflag;		/**< @brief  1 - the user specified the color */
-    char s_cflag;		/**< @brief  1 - use the default color */
-
-   /* Database object related info */
-    char s_Eflag;		/**< @brief  flag - not a solid but an "E'd" region (MGED ONLY)*/
-    short s_regionid;		/**< @brief  region ID (MGED ONLY)*/
-};
-
-/* A display list corresponds (typically) to a database object.  It is composed of one
- * or more scene objects, which can be manipulated independently but collectively make
- * up the displayed representation of an object. */
-struct display_list {
-    struct bu_list      l;
-    void               *dl_dp;                 /* Normally this will be a struct directory pointer */
-    struct bu_vls       dl_path;
-    struct bu_list      dl_head_scene_obj;          /**< @brief  head of scene obj list for this display list */
-    int                 dl_wflag;
-};
-
-struct bv_data_axes_state {
-    int       draw;
-    int       color[3];
-    int       line_width;          /* in pixels */
-    fastf_t   size;                /* in view coordinates */
-    int       num_points;
-    point_t   *points;             /* in model coordinates */
-};
-
-struct bv_data_arrow_state {
-    int       gdas_draw;
-    int       gdas_color[3];
-    int       gdas_line_width;          /* in pixels */
-    int       gdas_tip_length;
-    int       gdas_tip_width;
-    int       gdas_num_points;
-    point_t   *gdas_points;             /* in model coordinates */
-};
-
-struct bv_data_label_state {
-    int         gdls_draw;
-    int         gdls_color[3];
-    int         gdls_num_labels;
-    int         gdls_size;
-    char        **gdls_labels;
-    point_t     *gdls_points;
-};
-
-struct bv_data_line_state {
-    int       gdls_draw;
-    int       gdls_color[3];
-    int       gdls_line_width;          /* in pixels */
-    int       gdls_num_points;
-    point_t   *gdls_points;             /* in model coordinates */
-};
-
-typedef struct {
-    int                 gdps_draw;
-    int                 gdps_moveAll;
-    int                 gdps_color[3];
-    int                 gdps_line_width;        /* in pixels */
-    int                 gdps_line_style;
-    int                 gdps_cflag;             /* contour flag */
-    size_t              gdps_target_polygon_i;
-    size_t              gdps_curr_polygon_i;
-    size_t              gdps_curr_point_i;
-    point_t             gdps_prev_point;
-    bg_clip_t           gdps_clip_type;
-    fastf_t             gdps_scale;
-    point_t             gdps_origin;
-    mat_t               gdps_rotation;
-    mat_t               gdps_view2model;
-    mat_t               gdps_model2view;
-    struct bg_polygons  gdps_polygons;
-    fastf_t             gdps_data_vZ;
-} bv_data_polygon_state;
-
-
-/* A note about the vZ parameter...
- *
- * gv_data_vZ is an internal parameter used by commands creating and
- * manipulating data objects.  Geometrically, it is a magnitude in the
- * direction of the Z vector of the view plane. Functionally, what it
- * allows the code to do is define a 2D plane embedded in in 3D space that
- * is offset from but parallel to the view plane - in an orthogonal view
- * this corresponds to objects drawn in that plane being "above" or "below"
- * objects defined within the view plane itself.
- *
- * Visually, objects drawn in this fashion in orthogonal views will be
- * indistinguishable regardless of their vZ offset - it is only when the
- * view is rotated that the user will be able to see the "above" and
- * "below" effect of creating view objects with differing vZ values.
- *
- * Users will generally not want to set gv_data_vZ directly, as it is a view
- * space value and may not behave intuitively.  Commands are defined to
- * calculate vZ values based on model spaces inputs, and these should be
- * used to generate the value supplied to gv_data_vZ.
- */
-struct bv_data_tclcad {
-    int           		gv_polygon_mode;  // libtclcad polygon modes
-    int		  		gv_hide;          // libtclcad setting for hiding view - unused?
-    fastf_t       		gv_data_vZ;
-    struct bv_data_arrow_state	gv_data_arrows;
-    struct bv_data_axes_state	gv_data_axes;
-    struct bv_data_label_state	gv_data_labels;
-    struct bv_data_line_state	gv_data_lines;
-    bv_data_polygon_state	gv_data_polygons;
-    struct bv_data_arrow_state	gv_sdata_arrows;
-    struct bv_data_axes_state	gv_sdata_axes;
-    struct bv_data_label_state	gv_sdata_labels;
-    struct bv_data_line_state	gv_sdata_lines;
-    bv_data_polygon_state	gv_sdata_polygons;
-    struct bv_other_state	gv_prim_labels;
-};
-
-#endif /* DM_BV_TCL_DATA_H */
-
-/** @} */
-/*
- * Local Variables:
- * mode: C
- * tab-width: 8
- * indent-tabs-mode: t
- * c-file-style: "stroustrup"
- * End:
- * ex: shiftwidth=4 tabstop=8
- */

include/bv/util.h

@@ -1,431 +0,0 @@
-/*                      B V I E W _ U T I L . H
- * BRL-CAD
- *
- * Copyright (c) 1993-2026 United States Government as represented by
- * the U.S. Army Research Laboratory.
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public License
- * version 2.1 as published by the Free Software Foundation.
- *
- * This library is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this file; see the file named COPYING for more
- * information.
- */
-/** @addtogroup bv_util
- *
- */
-/** @{ */
-/** @file bv/util.h */
-
-#ifndef BV_UTIL_H
-#define BV_UTIL_H
-
-#include "common.h"
-#include "bu/hash.h"
-#include "bn/tol.h"
-#include "dm/defines.h"
-#include "bv/defines.h"
-
-__BEGIN_DECLS
-
-/* Set default values for a bv. */
-BV_EXPORT extern void bv_init(struct bview *v, struct bview_set *s);
-BV_EXPORT extern void bv_free(struct bview *v);
-
-/**
- * FIXME: this routine is suspect and needs investigating.  if run
- * during view initialization, the shaders regression test fails.
- */
-BV_EXPORT void bv_mat_aet(struct bview *v);
-
-BV_EXPORT extern void bv_settings_init(struct bview_settings *s);
-
-/* To use default scaling (0.5 model scale == 2.0 view factor) use
- * this as an argument to bv_autoview's scale parameter */
-#define BV_AUTOVIEW_SCALE_DEFAULT -1
-/**
- * Automatically set up the view to make the scene objects visible
- */
-BV_EXPORT extern void bv_autoview(struct bview *v, fastf_t scale, int all_view_objs);
-
-/**
- * Set up the view (center and size) to frame the supplied bounding box.
- * Pass BV_AUTOVIEW_SCALE_DEFAULT as the scale argument to use the
- * default scaling factor.  This is the back end bv_autoview() uses once
- * a bounding box has been determined.
- */
-BV_EXPORT extern void bv_autoview_bounds(struct bview *v, fastf_t scale, const point_t min, const point_t max);
-
-/* Copy the size and camera info (deliberately not a full copy of all view state) */
-BV_EXPORT extern void bv_sync(struct bview *dest, struct bview *src);
-
-
-
-/* Camera accessor functions
- *
- * These replace direct writes to gv_scale / gv_size / gv_isize / gv_perspective /
- * gv_aet / gv_rotation / gv_center, ensuring derived fields are kept consistent
- * and view-policy decisions stay above the scene-data layer.
- *
- * Size and scale are linked: size == 2 * scale; isize == 1 / size.
- * Setters maintain all three automatically. */
-BV_EXPORT extern fastf_t bv_view_get_scale(const struct bview *v);
-BV_EXPORT extern void    bv_view_set_scale(struct bview *v, fastf_t scale);
-BV_EXPORT extern fastf_t bv_view_get_size(const struct bview *v);
-BV_EXPORT extern void    bv_view_set_size(struct bview *v, fastf_t size);
-
-/* Perspective angle (degrees; 0 means orthographic). */
-BV_EXPORT extern fastf_t bv_view_get_perspective(const struct bview *v);
-BV_EXPORT extern void    bv_view_set_perspective(struct bview *v, fastf_t perspective);
-
-/* Azimuth / Elevation / Twist.  bv_view_set_aet recomputes gv_rotation. */
-BV_EXPORT extern void bv_view_get_aet(const struct bview *v, vect_t aet);
-BV_EXPORT extern void bv_view_set_aet(struct bview *v, const vect_t aet);
-
-/* Raw rotation matrix.  Prefer bv_view_set_aet when the AET representation is
- * available; use this accessor only when restoring saved matrix state (e.g.
- * loadview). */
-BV_EXPORT extern void bv_view_get_rotation(const struct bview *v, mat_t rot);
-BV_EXPORT extern void bv_view_set_rotation(struct bview *v, const mat_t rot);
-
-/* View center expressed as a point (positive = model origin offset).
- * get extracts the translation from gv_center; set stores it via
- * MAT_DELTAS_VEC_NEG so gv_center holds the negated translation. */
-BV_EXPORT extern void bv_view_get_center_vec(const struct bview *v, point_t center);
-BV_EXPORT extern void bv_view_set_center_vec(struct bview *v, const point_t center);
-
-
-
-/* Copy settings (potentially) common to the view and scene objects.
- * Return 0 if no changes were made to dest.  If dest did have one
- * or more settings updated from src, return 1. */
-BV_EXPORT extern int bv_obj_settings_sync(struct bv_obj_settings *dest, struct bv_obj_settings *src);
-
-/* Sync values within the bv, perform callbacks if any are defined */
-BV_EXPORT extern void bv_update(struct bview *gvp);
-
-/* Update objects in the selection set (if any) and their children */
-BV_EXPORT extern int bv_update_selected(struct bview *gvp);
-
-/* Clear or reset the knob states.  Specify a category to indicate which
- * variables should be reset:
- *
- * BV_KNOBS_ALL resets both rate and absolute values
- * BV_KNOBS_RATE resets rate only
- * BV_KNOBS_ABS resets absolute only
- */
-#define BV_KNOBS_ALL 0
-#define BV_KNOBS_RATE 1
-#define BV_KNOBS_ABS 2
-BV_EXPORT extern void bv_knobs_reset(struct bview_knobs *k, int category);
-
-/* Hash the semantic (non-pointer) contents of a bview_knobs struct.  This
- * intentionally excludes any *_udata pointers to avoid pointer address noise
- * and skips any padding that would be present if hashing the raw struct.
- *
- * If 'state' is non-NULL the supplied hash state is updated in-place and the
- * function returns 0 (the caller is expected to finalize the hash later.)
- * If 'state' is NULL an internal hash state is created, populated and
- * finalized and the resulting hash value is returned.
- *
- * Returns:
- *   0     if k is NULL or state supplied (non-owning mode)
- *   hash  if state is NULL (owning mode)
- */
-BV_EXPORT extern unsigned long long
-bv_knobs_hash(struct bview_knobs *k, struct bu_data_hash_state *state);
-
-/**
- * @brief
- * Process an individual libbv knob command.
- *
- * Note that the reason rvec, do_rot, tvec and do_tran are set, rather than an
- * immediate view update being performed, is to allow parent applications to
- * process multiple commands before finally triggering the bv_knobs_rot or
- * bv_knobs_tran functions to implement the accumulated instructions.
- *
- * @param[out] rvec     Pointer to rotation vector
- * @param[out] do_rot   Pointer to flag indicating whether the command implies a rotation op is needed
- * @param[out] tvec     Pointer to translation vector
- * @param[out] do_tran  Pointer to flag indicating whether the command implies a translation op is needed
- *
- * @param[in] v          bview structure
- * @param[in] cmd        command string - valid entries are x, y, z, X, Y Z, ax, ay, az, aX, aY, aZ, S, aS
- * @param[in] f          numerical parameter to cmd (i.e. aX 0.1 - required for all commands)
- * @param[in] origin     char indicating origin - may be 'e' (eye_pt), 'm' (model origin) or 'v' (view origin - default)
- * @param[in] model_flag Manipulate view using model coordinates rather than view coordinates
- * @param[in] incr_flag  Treat f parameter as an incremental change rather than an absolute setting
- *
- * @return
- * Returns BRLCAD_OK if command was successfully processed, BRLCAD_ERROR otherwise.
- * */
-BV_EXPORT extern int bv_knobs_cmd_process(
-	vect_t *rvec, int *do_rot, vect_t *tvec, int *do_tran,
-        struct bview *v, const char *cmd, fastf_t f,
-        char origin, int model_flag, int incr_flag
-	);
-
-/**
- * @brief
- * Rotate the view based on an Euler angle triplet (degrees) specified
- * in one of several coordinate frames, about one of several origins.
- *
- * coords:  Rotation input frame
- *   'v' - rvec in view coordinates
- *   'm' - rvec in model coordinates (converted via Rv * Rm * Rv^{-1})
- *   'o' - rvec in object coordinates (use obj_rot to map object->model->view,
- *         fallback to 'v' semantics if obj_rot is NULL)
- *
- * origin:  Rotation pivot specifier
- *   'v' : view center (0,0,0 in view space)
- *   'm' : model origin
- *   'e' : eye point (0,0,1 in view space)
- *   'k' : model-space custom pivot supplied via pvt_pt
- *   Any unrecognized value falls back to 'v'.
- *
- * obj_rot:
- *   Accumulated object->model rotation matrix when coords=='o'. NULL otherwise.
- *
- * pvt_pt:
- *   Model-space pivot point when origin=='k'. Ignored otherwise.
- *   NULL == model origin.
- *
- * BEHAVIOR
- * 1. rvec is converted into a pure view-space rotation matrix according
- *    to 'coords' (and obj_rot for 'o').
- * 2. If origin != 'v', the view center (gv_center) is relocated so the
- *    specified pivot is invariant under the applied rotation.
- * 3. gv_rotation is post-multiplied by the view rotation matrix.
- * 4. bv_update(v) refreshes derived matrices. Absolute translation bookkeeping
- *    (tra_v_abs / tra_m_abs) is always recomputed
- *
- * @param[in,out] v      target bview structure
- * @param[in] rvec       rotation vector (Euler angles, degrees) expressed in the coordinate frame indicated by coords.
- * @param[in] origin     char indicating origin - may be 'e' (eye_pt), 'm' (model origin), 'v' (view origin - default) or 'k' (keypoint)
- * @param[in] coords     coordinate frame - may be 'm' (model), 'o' (obj coords via obj_rot), or 'v' (view)
- * @param[in] obj_rot    pointer to accumulated object rotation matrix (may be NULL)
- * @param[in] pvt_pt     model space pivot point
- */
-BV_EXPORT extern void
-bv_knobs_rot(struct bview *v,
-	const vect_t rvec,
-	char origin,
-	char coords,
-	const matp_t obj_rot,
-	const pointp_t pvt_pt);
-
-/* @brief
- * Process a knob translation vector.
- *
- * @param[in] v          bview structure
- * @param[in] tvec      Pointer to translation vector
- * @param[in] model_flag Manipulate view using model coordinates rather than view coordinates
- */
-BV_EXPORT extern void
-bv_knobs_tran(struct bview *v,
-	const vect_t tvec,
-	int model_flag);
-
-
-/* Update the bview struct's knob rate flags based on the vector values. */
-BV_EXPORT extern void
-bv_update_rate_flags(struct bview *v);
-
-
-/* Return 1 if the visible contents differ
- * Return 2 if visible content is the same but settings differ
- * Return 3 if content is the same but user data, dmp or callbacks differ
- * Return -1 if one or more of the views is NULL
- * Else return 0 */
-BV_EXPORT extern int bv_differ(struct bview *v1, struct bview *v2);
-
-/* Return a hash of the contents of the bv container.  Returns 0 on failure. */
-BV_EXPORT extern unsigned long long bv_hash(struct bview *v);
-
-/* Return a hash of the contents of a display list.  Returns 0 on failure. */
-BV_EXPORT extern unsigned long long bv_dl_hash(struct display_list *dl);
-
-/* Returns number of objects defined in any object container
- * known to this view (0 if completely cleared). */
-BV_EXPORT extern size_t bv_clear(struct bview *v, int flags);
-
-/* Note that some of these are mutually exclusive as far as producing any
- * changes - a simultaneous constraint in X and Y, for example, results in a
- * no-op. */
-#define BV_IDLE       0x000
-#define BV_ROT        0x001
-#define BV_TRANS      0x002
-#define BV_SCALE      0x004
-#define BV_CENTER     0x008
-#define BV_CON_X      0x010
-#define BV_CON_Y      0x020
-#define BV_CON_Z      0x040
-#define BV_CON_GRID   0x080
-#define BV_CON_LINES  0x100
-
-/* Update a view in response to X,Y coordinate changes as generated
- * by a graphical interface's mouse motion. */
-BV_EXPORT extern int bv_adjust(struct bview *v, int dx, int dy, point_t keypoint, int mode, unsigned long long flags);
-
-/* Beginning extraction of the core of libtclcad view object manipulation
- * logic.  The following functions will initially be pretty straightforward
- * mappings from libtclcad, and will likely evolve over time.
- */
-
-/* Return -1 if width and/or height are unset (and hence a meaningful
- * calculation is impossible), else 0. */
-BV_EXPORT extern int bv_screen_to_view(struct bview *v, fastf_t *fx, fastf_t *fy, fastf_t x, fastf_t y);
-
-/* Return -1 if width and/or height are unset (and hence a meaningful
- * calculation is impossible), else 0.
- *
- * x and y will normally be integers, but the types are float to allow for
- * the possibility of sub-pixel coordinate specifications.
- */
-BV_EXPORT extern int bv_screen_pt(point_t *p, fastf_t x, fastf_t y, struct bview *v);
-
-
-
-/* Compute the min, max, and center points of the scene object.
- * Return 1 if a bound was computed, else 0 */
-BV_EXPORT extern int bv_scene_obj_bound(struct bv_scene_obj *s, struct bview *v);
-
-/* Find the nearest (mode == 0) or farthest (mode == 1) data_vZ value from
- * the vlist points in s in the context of view v */
-BV_EXPORT extern fastf_t bv_vZ_calc(struct bv_scene_obj *s, struct bview *v, int mode);
-
-/* Copy object attributes (but not geometry) from src to dest */
-BV_EXPORT extern void bv_obj_sync(struct bv_scene_obj *dest, struct bv_scene_obj *src);
-
-/* Mark object and any child objects as stale for the drawing routines */
-/* There are a few options for this situation - this one, which requires the client code
- * to explicitly notify the drawing routines they need to do work, an internal options
- * hash stored in the bv_scene_obj itself which is checked at render time, and setter
- * wrapper functions that do the bookkeeping for the caller (in lieu of directly setting
- * values in the bv_scene_obj struct.)  The first one isn't ideal because the visual will
- * be wrong if the caller doesn't supply the notification, the second has unknown
- * performance implications, and the third would be a major rework of how the bv_scene_obj
- * data is accessed (effectively, making the internal storage of bv_scene_obj fully hidden
- * a.l.a the libdm rework.)  Not sure what the best option is yet... leaning towards #2
- * if it is "fast enough"... */
-BV_EXPORT void bv_obj_stale(struct bv_scene_obj *s);
-
-/* Given a view, create an object of the specified type.  Like bv_obj_get, except it
- * leaves the addition of objects to the client.  Lower level. */
-BV_EXPORT struct bv_scene_obj *
-bv_obj_create(struct bview *v, int type);
-
-/* Given a view, create an object of the specified type and add it to the
- * appropriate container.  Issues such as memory management as a function of
- * view settings are handled internally, so client codes don't need to manage
- * it. */
-BV_EXPORT struct bv_scene_obj *
-bv_obj_get(struct bview *v, int type);
-
-/* Given an object, create an object that is a child of that object.  Issues
- * such as memory management as a function of view settings are handled
- * internally, so client codes don't need to manage it. */
-BV_EXPORT struct bv_scene_obj *
-bv_obj_get_child(struct bv_scene_obj *s);
-
-/* Clear the contents of an object (including releasing its children), but keep
- * it active in the view.  Generally used when redrawing an object */
-BV_EXPORT void
-bv_obj_reset(struct bv_scene_obj *s);
-
-/* Release an object to the internal pools. */
-BV_EXPORT void
-bv_obj_put(struct bv_scene_obj *o);
-
-/* Given a scene object and a name vname, glob match child names and uuids to
- * attempt to locate a child of s that matches vname */
-BV_EXPORT struct bv_scene_obj *
-bv_find_child(struct bv_scene_obj *s, const char *vname);
-
-/* Given a view and a name vname, glob match names and uuids to attempt to
- * locate a scene object in v that matches vname.
- *
- * NOTE - currently this is searching the top level objects, but does not walk
- * down into their children.  May want to support that in the future... */
-BV_EXPORT struct bv_scene_obj *
-bv_find_obj(struct bview *v, const char *vname);
-
-/* Given a seed name, generate a name that does not collide with any existing
- * object names in the top level.  If the seed name does not collide, it is
- * returned as the result - otherwise, a name based on the seed name will be
- * generated.
- */
-BV_EXPORT void
-bv_uniq_obj_name(struct bu_vls *oname, const char *seed, struct bview *v);
-
-/* For the specified object/view pairing, return the appropriate scene object
- * to use with that view.  Usually this will return s, but if a Level of Detail
- * scheme or some other view-aware rendering of the object is active, that object
- * will be returned instead. */
-BV_EXPORT struct bv_scene_obj *
-bv_obj_for_view(struct bv_scene_obj *s, struct bview *v);
-
-/* Get a view-specific object vobj for view v on object s.  */
-BV_EXPORT struct bv_scene_obj *
-bv_obj_get_vo(struct bv_scene_obj *s, struct bview *v);
-
-/* Check for the presence of view-specific objects */
-BV_EXPORT int
-bv_obj_have_vo(struct bv_scene_obj *s, struct bview *v);
-
-/* Clear view-specific objects */
-BV_EXPORT int
-bv_clear_view_obj(struct bv_scene_obj *s, struct bview *v);
-
-/* Set the illumination state on the object and its children to ill_state.
- * Returns 0 if no states were changed, and 1 if one or more states were
- * updated. */
-BV_EXPORT int
-bv_illum_obj(struct bv_scene_obj *s, char ill_state);
-
-/* For the given view, return a pointer to the bu_ptbl holding active scene
- * objects with the specified type.  Note that view-specific db objects are not
- * part of these sets - they should be retrieved from the scene objects in this
- * set with bv_obj_for_view. */
-BV_EXPORT struct bu_ptbl *
-bv_view_objs(struct bview *v, int type);
-
-/* Given a view, construct the view plane */
-BV_EXPORT int
-bv_view_plane(plane_t *p, struct bview *v);
-
-
-/* Environment variable controlled logging.
- *
- * Set BV_LOG to numerical levels to get increasingly
- * verbose reporting of drawing info */
-#define BV_ENABLE_ENV_LOGGING 1
-BV_EXPORT void
-bv_log(int level, const char *fmt, ...)  _BU_ATTR_PRINTF23;
-
-
-/* Debugging function for printing contents of views */
-BV_EXPORT void
-bv_view_print(const char *title, struct bview *v, int verbosity);
-
-__END_DECLS
-
-/** @} */
-
-#endif /* BV_UTIL_H */
-
-/*
- * Local Variables:
- * mode: C
- * tab-width: 8
- * indent-tabs-mode: t
- * c-file-style: "stroustrup"
- * End:
- * ex: shiftwidth=4 tabstop=8
- */

include/bv/vlist.h

@@ -1,346 +0,0 @@
-/*                        V L I S T . H
- * BRL-CAD
- *
- * Copyright (c) 2004-2026 United States Government as represented by
- * the U.S. Army Research Laboratory.
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public License
- * version 2.1 as published by the Free Software Foundation.
- *
- * This library is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this file; see the file named COPYING for more
- * information.
- */
-/** @addtogroup bv_vlist
- *
- * @brief
- * Definitions for handling lists of vectors (really vertices, or
- * points) and polygons in 3-space.  Intended for common handling of
- * wireframe display information, in the full resolution that is
- * calculated in.
- *
- * On 32-bit machines, BV_VLIST_CHUNK of 35 results in bv_vlist
- * structures just less than 1k bytes.
- *
- * The head of the doubly linked list can be just a "struct bu_list"
- * head.
- *
- * To visit all the elements in the vlist:
- *	for (BU_LIST_FOR(vp, bv_vlist, hp)) {
- *		int	i;
- *		int	nused = vp->nused;
- *		int	*cmd = vp->cmd;
- *		point_t *pt = vp->pt;
- *		for (i = 0; i < nused; i++, cmd++, pt++) {
- *			access(*cmd, *pt);
- *			access(vp->cmd[i], vp->pt[i]);
- *		}
- *	}
- */
-/** @{ */
-/** @file bv/vlist.h */
-
-#ifndef BV_VLIST_H
-#define BV_VLIST_H
-
-#include "common.h"
-#include <stdio.h> /* for FILE */
-#include "vmath.h"
-#include "bu/magic.h"
-#include "bu/list.h"
-#include "bu/malloc.h"
-#include "bu/vls.h"
-#include "bv/defines.h"
-
-__BEGIN_DECLS
-
-#define BV_VLIST_CHUNK 35		/**< @brief 32-bit mach => just less than 1k */
-
-struct bv_vlist  {
-    struct bu_list l;		/**< @brief magic, forw, back */
-    size_t nused;		/**< @brief elements 0..nused active */
-    int cmd[BV_VLIST_CHUNK];	/**< @brief VL_CMD_* */
-    point_t pt[BV_VLIST_CHUNK];	/**< @brief associated 3-point/vect */
-};
-#define BV_VLIST_NULL	((struct bv_vlist *)0)
-#define BV_CK_VLIST(_p) BU_CKMAG((_p), BV_VLIST_MAGIC, "bv_vlist")
-
-/* should these be enum? -Erik */
-/* Values for cmd[] */
-#define BV_VLIST_LINE_MOVE		0	/**< @brief specify new line */
-#define BV_VLIST_LINE_DRAW		1	/**< @brief subsequent line vertex */
-#define BV_VLIST_POLY_START		2	/**< @brief pt[] has surface normal */
-#define BV_VLIST_POLY_MOVE		3	/**< @brief move to first poly vertex */
-#define BV_VLIST_POLY_DRAW		4	/**< @brief subsequent poly vertex */
-#define BV_VLIST_POLY_END		5	/**< @brief last vert (repeats 1st), draw poly */
-#define BV_VLIST_POLY_VERTNORM		6	/**< @brief per-vertex normal, for interpolation */
-#define BV_VLIST_TRI_START		7	/**< @brief pt[] has surface normal */
-#define BV_VLIST_TRI_MOVE		8	/**< @brief move to first triangle vertex */
-#define BV_VLIST_TRI_DRAW		9	/**< @brief subsequent triangle vertex */
-#define BV_VLIST_TRI_END		10	/**< @brief last vert (repeats 1st), draw poly */
-#define BV_VLIST_TRI_VERTNORM		11	/**< @brief per-vertex normal, for interpolation */
-#define BV_VLIST_POINT_DRAW		12	/**< @brief Draw a single point */
-#define BV_VLIST_POINT_SIZE		13	/**< @brief specify point pixel size */
-#define BV_VLIST_LINE_WIDTH		14	/**< @brief specify line pixel width */
-#define BV_VLIST_DISPLAY_MAT		15	/**< @brief specify the model matrix */
-#define BV_VLIST_MODEL_MAT		16	/**< @brief specify the display matrix */
-#define BV_VLIST_CMD_MAX		16	/**< @brief Max command number */
-/**
- * Applications that are going to use BV_ADD_VLIST and BV_GET_VLIST
- * are required to execute this macro once, on their _free_hd:
- * BU_LIST_INIT(&_free_hd);
- *
- * Note that BV_GET_VLIST and BV_FREE_VLIST are non-PARALLEL.
- */
-#define BV_GET_VLIST(_free_hd, p) do {\
-	(p) = BU_LIST_FIRST(bv_vlist, (_free_hd)); \
-	if (BU_LIST_IS_HEAD((p), (_free_hd))) { \
-	    BU_ALLOC((p), struct bv_vlist); \
-	    (p)->l.magic = BV_VLIST_MAGIC; \
-	} else { \
-	    BU_LIST_DEQUEUE(&((p)->l)); \
-	} \
-	(p)->nused = 0; \
-    } while (0)
-
-/** Place an entire chain of bv_vlist structs on the freelist _free_hd */
-#define BV_FREE_VLIST(_free_hd, hd) do { \
-	BU_CK_LIST_HEAD((hd)); \
-	BU_LIST_APPEND_LIST((_free_hd), (hd)); \
-    } while (0)
-
-#define BV_ADD_VLIST(_free_hd, _dest_hd, pnt, draw) do { \
-	struct bv_vlist *_vp; \
-	BU_CK_LIST_HEAD(_dest_hd); \
-	_vp = BU_LIST_LAST(bv_vlist, (_dest_hd)); \
-	if (BU_LIST_IS_HEAD(_vp, (_dest_hd)) || (_vp && _vp->nused >= BV_VLIST_CHUNK)) { \
-	    BV_GET_VLIST(_free_hd, _vp); \
-	    BU_LIST_INSERT((_dest_hd), &(_vp->l)); \
-	} \
-	VMOVE(_vp->pt[_vp->nused], (pnt)); \
-	_vp->cmd[_vp->nused++] = (draw); \
-    } while (0)
-
-/** Change the transformation matrix to display */
-#define BV_VLIST_SET_DISP_MAT(_free_hd, _dest_hd, _ref_pt) do { \
-	struct bv_vlist *_vp; \
-	BU_CK_LIST_HEAD(_dest_hd); \
-	_vp = BU_LIST_LAST(bv_vlist, (_dest_hd)); \
-	if (BU_LIST_IS_HEAD(_vp, (_dest_hd)) || (_vp && _vp->nused >= BV_VLIST_CHUNK)) { \
-	    BV_GET_VLIST(_free_hd, _vp); \
-	    BU_LIST_INSERT((_dest_hd), &(_vp->l)); \
-	} \
-	VMOVE(_vp->pt[_vp->nused], (_ref_pt)); \
-	_vp->cmd[_vp->nused++] = BV_VLIST_DISPLAY_MAT; \
-    } while (0)
-
-/** Change the transformation matrix to model */
-#define BV_VLIST_SET_MODEL_MAT(_free_hd, _dest_hd) do { \
-	struct bv_vlist *_vp; \
-	BU_CK_LIST_HEAD(_dest_hd); \
-	_vp = BU_LIST_LAST(bv_vlist, (_dest_hd)); \
-	if (BU_LIST_IS_HEAD(_vp, (_dest_hd)) || (_vp && _vp->nused >= BV_VLIST_CHUNK)) { \
-	    BV_GET_VLIST(_free_hd, _vp); \
-	    BU_LIST_INSERT((_dest_hd), &(_vp->l)); \
-	} \
-	_vp->cmd[_vp->nused++] = BV_VLIST_MODEL_MAT; \
-    } while (0)
-
-/** Set a point size to apply to the vlist elements that follow. */
-#define BV_VLIST_SET_POINT_SIZE(_free_hd, _dest_hd, _size) do { \
-	struct bv_vlist *_vp; \
-	BU_CK_LIST_HEAD(_dest_hd); \
-	_vp = BU_LIST_LAST(bv_vlist, (_dest_hd)); \
-	if (BU_LIST_IS_HEAD(_vp, (_dest_hd)) || (_vp && _vp->nused >= BV_VLIST_CHUNK)) { \
-	    BV_GET_VLIST(_free_hd, _vp); \
-	    BU_LIST_INSERT((_dest_hd), &(_vp->l)); \
-	} \
-	_vp->pt[_vp->nused][0] = (_size); \
-	_vp->cmd[_vp->nused++] = BV_VLIST_POINT_SIZE; \
-    } while (0)
-
-/** Set a line width to apply to the vlist elements that follow. */
-#define BV_VLIST_SET_LINE_WIDTH(_free_hd, _dest_hd, _width) do { \
-	struct bv_vlist *_vp; \
-	BU_CK_LIST_HEAD(_dest_hd); \
-	_vp = BU_LIST_LAST(bv_vlist, (_dest_hd)); \
-	if (BU_LIST_IS_HEAD(_vp, (_dest_hd)) || (_vp && _vp->nused >= BV_VLIST_CHUNK)) { \
-	    BV_GET_VLIST(_free_hd, _vp); \
-	    BU_LIST_INSERT((_dest_hd), &(_vp->l)); \
-	} \
-	_vp->pt[_vp->nused][0] = (_width); \
-	_vp->cmd[_vp->nused++] = BV_VLIST_LINE_WIDTH; \
-    } while (0)
-
-
-BV_EXPORT extern size_t bv_vlist_cmd_cnt(struct bv_vlist *vlist);
-BV_EXPORT extern int bv_vlist_bbox(struct bu_list *vlistp, point_t *bmin, point_t *bmax, size_t *length, int *dispmode);
-
-
-
-/**
- * For plotting, a way of separating plots into separate color vlists:
- * blocks of vlists, each with an associated color.
- */
-struct bv_vlblock {
-    uint32_t magic;
-    size_t nused;
-    size_t max;
-    long *rgb;		/**< @brief rgb[max] variable size array */
-    struct bu_list *head;		/**< @brief head[max] variable size array */
-    struct bu_list *free_vlist_hd;	/**< @brief where to get/put free vlists */
-};
-#define BV_CK_VLBLOCK(_p)	BU_CKMAG((_p), BV_VLBLOCK_MAGIC, "bv_vlblock")
-
-
-/**
- * Convert a string to a vlist.
- *
- * 'scale' is the width, in mm, of one character.
- *
- * @param vhead   vhead
- * @param free_hd source of free vlists
- * @param string  string of chars to be plotted
- * @param origin  lower left corner of 1st char
- * @param rot	  Transform matrix (WARNING: may xlate)
- * @param scale   scale factor to change 1x1 char sz
- *
- */
-BV_EXPORT extern void bv_vlist_3string(struct bu_list *vhead,
-				       struct bu_list *free_hd,
-				       const char *string,
-				       const point_t origin,
-				       const mat_t rot,
-				       double scale);
-
-/**
- * Convert string to vlist in 2D
- *
- * A simpler interface, for those cases where the text lies in the X-Y
- * plane.
- *
- * @param vhead		vhead
- * @param free_hd	source of free vlists
- * @param string	string of chars to be plotted
- * @param x		lower left corner of 1st char
- * @param y		lower left corner of 1st char
- * @param scale		scale factor to change 1x1 char sz
- * @param theta 	degrees ccw from X-axis
- *
- */
-BV_EXPORT extern void bv_vlist_2string(struct bu_list *vhead,
-				       struct bu_list *free_hd,
-				       const char *string,
-				       double x,
-				       double y,
-				       double scale,
-				       double theta);
-
-/**
- * Returns the description of a vlist cmd.  Caller is responsible
- * for freeing the returned string.
- */
-BV_EXPORT extern const char *bv_vlist_get_cmd_description(int cmd);
-
-/**
- * Validate an bv_vlist chain for having reasonable values inside.
- * Calls bu_bomb() if not.
- *
- * Returns -
- * npts Number of point/command sets in use.
- */
-BV_EXPORT extern size_t bv_ck_vlist(const struct bu_list *vhead);
-
-
-/**
- * Duplicate the contents of a vlist.  Note that the copy may be more
- * densely packed than the source.
- */
-BV_EXPORT extern void bv_vlist_copy(struct bu_list *vlists,
-				    struct bu_list *dest,
-				    const struct bu_list *src);
-
-
-/**
- * Convert a vlist chain into a blob of network-independent binary,
- * for transmission to another machine.
- *
- * The result is stored in a vls string, so that both the address and
- * length are available conveniently.
- */
-BV_EXPORT extern void bv_vlist_export(struct bu_vls *vls,
-				      struct bu_list *hp,
-				      const char *name);
-
-
-/**
- * Convert a blob of network-independent binary prepared by
- * vls_vlist() and received from another machine, into a vlist chain.
- */
-BV_EXPORT extern void bv_vlist_import(struct bu_list *vlists,
-				      struct bu_list *hp,
-				      struct bu_vls *namevls,
-				      const unsigned char *buf);
-
-BV_EXPORT extern void bv_vlist_cleanup(struct bu_list *hd);
-
-BV_EXPORT extern struct bv_vlblock *bv_vlblock_init(struct bu_list *free_vlist_hd, /* where to get/put free vlists */
-						    int max_ent);
-
-BV_EXPORT extern void bv_vlblock_free(struct bv_vlblock *vbp);
-
-BV_EXPORT extern struct bu_list *bv_vlblock_find(struct bv_vlblock *vbp,
-						 int r,
-						 int g,
-						 int b);
-
-
-BV_EXPORT void bv_vlist_rpp(struct bu_list *vlists, struct bu_list *hd, const point_t minn, const point_t maxx);
-
-/**
- * Output a bv_vlblock object in extended UNIX-plot format, including
- * color.
- */
-BV_EXPORT extern void bv_plot_vlblock(FILE *fp,
-				      const struct bv_vlblock *vbp);
-
-BV_EXPORT extern void bv_vlblock_to_objs(struct bu_ptbl *out,
-                                     const char *name_root,
-				     struct bv_vlblock *vbp,
-				     struct bview *v,
-				     struct bv_scene_obj *f,
-				     struct bu_list *vlfree);
-
-
-BV_EXPORT extern struct bv_scene_obj *
-bv_vlblock_obj(struct bv_vlblock *vbp, struct bview *v, const char *name);
-
-/**
- * Output a vlist as an extended 3-D floating point UNIX-Plot file.
- * You provide the file.  Uses libplot3 routines to create the
- * UNIX-Plot output.
- */
-BV_EXPORT extern void bv_vlist_to_uplot(FILE *fp,
-					const struct bu_list *vhead);
-
-/** @} */
-
-__END_DECLS
-
-#endif  /* BV_VLIST_H */
-
-/*
- * Local Variables:
- * mode: C
- * tab-width: 8
- * indent-tabs-mode: t
- * c-file-style: "stroustrup"
- * End:
- * ex: shiftwidth=4 tabstop=8
- */

include/dm.h

@@ -31,7 +31,7 @@
 #include "vmath.h"
 #include "bu/vls.h"
 #include "bn.h"
-#include "bv.h"
+#include "bsg.h"
 #include "icv.h"
 
 #include "./dm/defines.h"
@@ -82,8 +82,6 @@ DM_EXPORT extern void *dm_interp(struct dm *dmp);
 DM_EXPORT extern void *dm_get_ctx(struct dm *dmp);
 DM_EXPORT extern void *dm_get_udata(struct dm *dmp);
 DM_EXPORT extern void dm_set_udata(struct dm *dmp, void *udata);
-DM_EXPORT extern int dm_share_dlist(struct dm *dmp1,
-				    struct dm *dmp2);
 DM_EXPORT extern fastf_t dm_Xx2Normal(struct dm *dmp,
 				      int x);
 DM_EXPORT extern int dm_Normal2Xx(struct dm *dmp,
@@ -100,20 +98,16 @@ DM_EXPORT extern int dm_processOptions(struct dm *dmp, struct bu_vls *init_proc_
 
 /* adc.c */
 DM_EXPORT extern void dm_draw_adc(struct dm *dmp,
-				  struct bv_adc_state *adcp, mat_t view2model, mat_t model2view);
+				  struct bsg_adc_state *adcp, mat_t view2model, mat_t model2view);
 
 /* axes.c */
-DM_EXPORT extern void dm_draw_data_axes(struct dm *dmp,
-					fastf_t viewSize,
-					struct bv_data_axes_state *bndasp);
-
-DM_EXPORT extern void dm_draw_scene_axes(struct dm *dmp, struct bv_scene_obj *s);
+DM_EXPORT extern void dm_draw_scene_axes_payload(struct dm *dmp, const struct bsg_axes *axes);
 
 
 DM_EXPORT extern void dm_draw_hud_axes(struct dm *dmp,
 				   fastf_t viewSize,
 				   const mat_t rmat,
-				   struct bv_axes *bnasp);
+				   struct bsg_axes *bnasp);
 
 /* clip.c */
 DM_EXPORT extern int clip(fastf_t *,
@@ -127,7 +121,7 @@ DM_EXPORT extern int vclip(point_t,
 
 /* grid.c */
 DM_EXPORT extern void dm_draw_grid(struct dm *dmp,
-				   struct bv_grid_state *ggsp,
+				   struct bsg_grid_state *ggsp,
 				   fastf_t scale,
 				   mat_t model2view,
 				   fastf_t base2local);
@@ -148,7 +142,7 @@ DM_EXPORT extern int dm_draw_prim_labels(struct dm *dmp,
 
 /* rect.c */
 DM_EXPORT extern void dm_draw_rect(struct dm *dmp,
-				   struct bv_interactive_rect_state *grsp);
+				   struct bsg_interactive_rect_state *grsp);
 
 /* scale.c */
 DM_EXPORT extern void dm_draw_scale(struct dm *dmp,
@@ -194,17 +188,19 @@ DM_EXPORT extern int dm_graphical(const struct dm *dmp);
 DM_EXPORT extern const char *dm_get_type(struct dm *dmp);
 DM_EXPORT extern unsigned long dm_get_id(struct dm *dmp);
 DM_EXPORT extern void dm_set_id(struct dm *dmp, unsigned long new_id);
-DM_EXPORT extern int dm_get_displaylist(struct dm *dmp);
+DM_EXPORT extern int dm_get_backend_cache(struct dm *dmp);
 DM_EXPORT extern int dm_close(struct dm *dmp);
 DM_EXPORT extern int dm_get_bg(unsigned char **bg1, unsigned char **bg2, struct dm *dmp);
 DM_EXPORT extern int dm_set_bg(struct dm *dmp, unsigned char r1, unsigned char g1, unsigned char b1, unsigned char r2, unsigned char g2, unsigned char b2);
 DM_EXPORT extern unsigned char *dm_get_fg(struct dm *dmp);
 DM_EXPORT extern int dm_set_fg(struct dm *dmp, unsigned char r, unsigned char g, unsigned char b, int strict, fastf_t transparency);
+DM_EXPORT extern unsigned char *dm_get_geometry_default_color(struct dm *dmp);
+DM_EXPORT extern void dm_set_geometry_default_color(struct dm *dmp, unsigned char r, unsigned char g, unsigned char b);
 DM_EXPORT extern int dm_reshape(struct dm *dmp, int width, int height);
 DM_EXPORT extern int dm_make_current(struct dm *dmp);
 DM_EXPORT extern int dm_doevent(struct dm *dmp, void *clientData, void *eventPtr);
-DM_EXPORT extern int dm_get_dirty(struct dm *dmp);
-DM_EXPORT extern void dm_set_dirty(struct dm *dmp, int i);
+DM_EXPORT extern int dm_get_native_repaint_pending(struct dm *dmp);
+DM_EXPORT extern void dm_set_native_repaint_pending(struct dm *dmp, int i);
 DM_EXPORT extern vect_t *dm_get_clipmin(struct dm *dmp);
 DM_EXPORT extern vect_t *dm_get_clipmax(struct dm *dmp);
 DM_EXPORT extern int dm_get_stereo(struct dm *dmp);
@@ -225,8 +221,6 @@ DM_EXPORT extern void dm_set_linestyle(struct dm *dmp, int linestyle);
 DM_EXPORT extern int dm_get_perspective(struct dm *dmp);
 DM_EXPORT extern void dm_set_perspective(struct dm *dmp, fastf_t perspective);
 DM_EXPORT extern int dm_get_display_image(struct dm *dmp, unsigned char **image, int flip, int alpha);
-DM_EXPORT extern int dm_draw_vlist(struct dm *dmp, struct bv_vlist *vp);
-DM_EXPORT extern int dm_draw_vlist_hidden_line(struct dm *dmp, struct bv_vlist *vp);
 DM_EXPORT extern int dm_set_line_attr(struct dm *dmp, int width, int style);
 DM_EXPORT extern int dm_draw_begin(struct dm *dmp);
 DM_EXPORT extern int dm_draw_end(struct dm *dmp);
@@ -236,6 +230,7 @@ DM_EXPORT extern int dm_loadmatrix(struct dm *dmp, fastf_t *mat, int eye);
 DM_EXPORT extern int dm_loadpmatrix(struct dm *dmp, const fastf_t *mat);
 DM_EXPORT extern void dm_pop_pmatrix(struct dm *dmp);
 DM_EXPORT extern int dm_draw_string_2d(struct dm *dmp, const char *str, fastf_t x,  fastf_t y, int size, int use_aspect);
+DM_EXPORT extern int dm_draw_string_2d_rot(struct dm *dmp, const char *str, fastf_t x, fastf_t y, int size, int use_aspect, fastf_t angle);
 DM_EXPORT extern int dm_string_bbox_2d(struct dm *dmp, vect2d_t *bmin, vect2d_t *bmax, const char *str, fastf_t x,  fastf_t y, int size, int use_aspect);
 DM_EXPORT extern int dm_draw_line_2d(struct dm *dmp, fastf_t x1, fastf_t y1_2d, fastf_t x2, fastf_t y2);
 DM_EXPORT extern int dm_draw_line_3d(struct dm *dmp, point_t pt1, point_t pt2);
@@ -243,7 +238,6 @@ DM_EXPORT extern int dm_draw_lines_3d(struct dm *dmp, int npoints, point_t *poin
 DM_EXPORT extern int dm_draw_point_2d(struct dm *dmp, fastf_t x, fastf_t y);
 DM_EXPORT extern int dm_draw_point_3d(struct dm *dmp, point_t pt);
 DM_EXPORT extern int dm_draw_points_3d(struct dm *dmp, int npoints, point_t *points);
-DM_EXPORT extern int dm_draw(struct dm *dmp, struct bv_vlist *(*callback)(void *), void **data);
 DM_EXPORT extern int dm_set_depth_mask(struct dm *dmp, int d_on);
 DM_EXPORT extern int dm_set_debug(struct dm *dmp, int lvl);
 DM_EXPORT extern int dm_get_debug(struct dm *dmp);
@@ -269,48 +263,85 @@ DM_EXPORT extern void dm_set_bound_flag(struct dm *dmp, int bound);
 
 
 
-DM_EXPORT extern int dm_draw_obj(struct dm *dmp, struct bv_scene_obj *s);
-
-/* Dlist sensor API
+/* Modern renderer-backend contract.
  *
- * Sensors provide a push-based notification when a display list has been
- * regenerated, replacing per-frame polling of bv_scene_obj::s_dlist_stale.
+ * struct dm_backend_ops is the display-manager-side counterpart of
+ * bsg_backend_adapter.  A backend (dm-gl, dm-swrast, future dm-obol)
+ * registers a single static dm_backend_ops with each dm instance it
+ * creates; scene rendering invokes backend operations through the thin
+ * dm_backend_*() wrappers below, which forward resolved bsg_render_item
+ * records to the registered ops.
  *
- * dm_register_dlist_sensor  - attach a callback to be invoked whenever
- *                             dm_fire_dlist_sensors() is called on this dm.
- * dm_fire_dlist_sensors     - invoke all registered sensor callbacks; call
- *                             this after regenerating any display list.
- * dm_dlist_sensors_clear    - free all sensors registered on this dm. */
-DM_EXPORT extern int  dm_register_dlist_sensor(struct dm *dmp,
-					       struct bv_scene_obj *s,
-					       void (*callback)(struct bv_scene_obj *, void *),
-					       void *data);
-DM_EXPORT extern void dm_fire_dlist_sensors(struct dm *dmp);
-DM_EXPORT extern void dm_dlist_sensors_clear(struct dm *dmp);
+ * Lifecycle of a backend resource:
+ *  - draw_item:      per-frame draw of one resolved render item.  Required
+ *                    for scene graph rendering.
+ *  - invalidate_item: source data has changed; cached resources for the
+ *                    render item/source are stale. Optional.
+ *  - release_source: source has gone away; release backend-owned resources
+ *                    whose source identity matches. Optional.
+ *
+ * The actual backend_ops pointer lives in struct dm_impl (libdm-private)
+ * and is set during dm initialization. */
+struct bsg_render_request;
+struct bsg_render_item;
+struct dm_backend_resource;
 
+typedef void (*dm_backend_resource_free_fn)(struct dm *dmp,
+					    struct dm_backend_resource *resource);
+
+struct dm_backend_resource {
+    uint64_t cache_identity;
+    uint64_t source_identity;
+    uint64_t backend_identity;
+    uint64_t last_seen_generation;
+    unsigned int stale;
+    void *handle;
+    dm_backend_resource_free_fn free_resource;
+    struct dm_backend_resource *next;
+};
+
+struct dm_backend_ops {
+    uint32_t type_tag;                                                     /**< @brief backend type tag */
+    int  (*begin_frame)(struct dm *dmp);                                   /**< @brief optional backend frame begin */
+    int  (*draw_item)(struct dm *dmp, const struct bsg_render_item *item); /**< @brief resolved render-item draw; required for scene rendering */
+    void (*invalidate_item)(struct dm *dmp, const struct bsg_render_item *item, unsigned int reason_mask); /**< @brief mark item/source resources stale */
+    void (*release_source)(struct dm *dmp, uint64_t source_identity);      /**< @brief release resources for a render source */
+    void (*end_frame)(struct dm *dmp);                                     /**< @brief optional backend frame end */
+};
+
+/* Backend-ops accessors (libdm-private storage on dm_impl). */
+DM_EXPORT extern const struct dm_backend_ops *dm_get_backend_ops(struct dm *dmp);
+DM_EXPORT extern void dm_set_backend_ops(struct dm *dmp, const struct dm_backend_ops *ops);
+
+/* Backend-ops dispatch wrappers.  Each is safe to call with a NULL dmp or
+ * a NULL ops pointer.  Scene drawing requires draw_item; there is no node-only
+ * fallback from the modern render path. */
+DM_EXPORT extern int  dm_backend_draw_item(struct dm *dmp, const struct bsg_render_item *item);
+DM_EXPORT extern int  dm_backend_begin_frame(struct dm *dmp);
+DM_EXPORT extern void dm_backend_end_frame(struct dm *dmp);
+DM_EXPORT extern void dm_backend_invalidate_item(struct dm *dmp, const struct bsg_render_item *item, unsigned int reason_mask);
+DM_EXPORT extern void dm_backend_release_source(struct dm *dmp, uint64_t source_identity);
+
+DM_EXPORT extern struct dm_backend_resource *
+dm_backend_resource_get(struct dm *dmp,
+			uint64_t cache_identity,
+			uint64_t source_identity,
+			uint64_t backend_identity,
+			int create,
+			dm_backend_resource_free_fn free_resource);
+
+DM_EXPORT extern void
+dm_backend_resource_touch(struct dm *dmp, struct dm_backend_resource *resource);
+
+DM_EXPORT extern void
+dm_backend_resource_invalidate(struct dm *dmp, uint64_t source_identity);
+
+DM_EXPORT extern void
+dm_backend_resource_release_source(struct dm *dmp, uint64_t source_identity);
+
+DM_EXPORT extern void
+dm_backend_resource_reclaim_unseen(struct dm *dmp);
 
-/* Rather low level exposure of display list concepts.  Needed for MGED
- * and libtclcad, but we want to get to a point where the use (or not)
- * of display lists is an implementation level action rather than something
- * visible to the user. */
-DM_EXPORT extern int dm_gen_dlists(struct dm *dmp, size_t range);
-DM_EXPORT extern int dm_begin_dlist(struct dm *dmp, unsigned int list);
-DM_EXPORT extern int dm_draw_dlist(struct dm *dmp, unsigned int list);
-DM_EXPORT extern int dm_end_dlist(struct dm *dmp);
-DM_EXPORT extern int dm_free_dlists(struct dm *dmp, unsigned int list, int range);
-DM_EXPORT extern int dm_draw_display_list(struct dm *dmp, struct display_list *obj);
-DM_EXPORT extern int dm_draw_head_dl(struct dm *dmp,
-					  struct bu_list *dl,
-					  fastf_t transparency_threshold,
-					  fastf_t inv_viewsize,
-					  short r, short g, short b,
-					  int line_width,
-					  int draw_style,
-					  int draw_edit,
-					  unsigned char *gdc,
-					  int solids_down,
-					  int mv_dlist
-					 );
 
 // TODO - this should be using libicv  - right now this is just moving the guts
 // of dmo_png_cmd behind the call table, so only provides PNG...

include/dm/CMakeLists.txt

@@ -1,4 +1,4 @@
-set(dm_headers defines.h fbserv.h util.h view.h)
+set(dm_headers defines.h fbserv.h util.h view.h vlist.h)
 brlcad_manage_files(dm_headers ${INCLUDE_DIR}/brlcad/dm REQUIRED libdm)
 
 cmakefiles(CMakeLists.txt)

include/dm/fbserv.h

@@ -136,6 +136,20 @@ DM_EXPORT extern void fbs_setup_socket(int fd);
 DM_EXPORT extern int fbs_new_client(struct fbserv_obj *fbsp, struct pkg_conn *pcp, void *data);
 DM_EXPORT extern void fbs_existing_client_handler(void *clientData, int mask);
 
+/**
+ * @brief Tear down an fbserv client slot.
+ *
+ * Closes the libpkg connection, calls the registered TCP or IPC close
+ * handler, and resets the slot fields.  Safe to call from a
+ * Qt/Tcl/etc. handler that has detected EOF or an error on its
+ * fd-monitor channel and does not (or cannot) rely on the
+ * select-based fbs_existing_client_handler() path to do the drop.
+ *
+ * @p sub is the client index returned by fbs_new_client() / stored in
+ * fbsp->fbs_clients[*].  Out-of-range or unused indices are no-ops.
+ */
+DM_EXPORT extern void fbs_drop_client(struct fbserv_obj *fbsp, int sub);
+
 /**
  * @brief Open an IPC-based framebuffer server (no TCP listen socket).
  *

include/dm/view.h

@@ -33,7 +33,7 @@
 
 #include "bu/hash.h"
 #include "bu/vls.h"
-#include "bv/defines.h"
+#include "bsg/defines.h"
 #include "dm/defines.h"
 
 #ifndef DM_VIEW_H
@@ -52,28 +52,21 @@ struct dm_view_data {
     struct bu_hash_tbl  *edited_paths;
     struct bu_vls       *prim_label_list;
     int                 prim_label_list_size;
-    int                 dlist_on;
-    int                 refresh_on;
+    int                 cache_on;
 };
 
-DM_EXPORT extern void dm_draw_faceplate(struct bview *v);
+DM_EXPORT extern void dm_draw_faceplate(struct bsg_view *v);
 
 /* As a temporary measure, require client codes to specifically ask to enable
  * the bits that require librt in the headers if they're not going to be
  * calling them.  Not ideal, but pulling in rt also pulls in openNURBS, which
  * can have significant implications. */
 #ifdef DM_WITH_RT
-/* TODO - needed for dm_draw_labels, which cracks the database
- * objects to generate label info.  Need to think about how to
- * better handle this... - ideally should be a callback of some
- * sort on a bv scene object... */
 #include "rt/wdb.h"
-
-DM_EXPORT extern void dm_draw_viewobjs(struct rt_wdb *wdbp, struct bview *v, struct dm_view_data *d);
-#endif /* DM_NO_RT */
+#endif /* DM_WITH_RT */
 
 /* Stripped down form of dm_draw_viewobjs that does just what's needed for the new setup */
-DM_EXPORT extern void dm_draw_objs(struct bview *v, void (*dm_draw_custom)(struct bview *, void *), void *u_data);
+DM_EXPORT extern void dm_draw_objs(struct bsg_view *v);
 
 __END_DECLS
 

include/dm/vlist.h

@@ -0,0 +1,60 @@
+/*                       D M / V L I S T . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup libdm */
+/** @{ */
+/** @file dm/vlist.h
+ *
+ * Legacy display-manager vlist drawing API.
+ *
+ * New drawing code should publish typed BSG render records and render them
+ * through dm_backend_draw_item().  This header is isolated so modern dm.h
+ * clients do not inherit the legacy bsg_vlist dependency.
+ */
+
+#ifndef DM_VLIST_H
+#define DM_VLIST_H
+
+#include "common.h"
+
+#include "bsg/vlist.h"
+#include "dm/defines.h"
+
+__BEGIN_DECLS
+
+struct dm;
+
+DM_EXPORT extern int dm_draw(struct dm *dmp,
+			     bsg_vlist *(*callback)(void *),
+			     void **data);
+
+__END_DECLS
+
+#endif /* DM_VLIST_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/gcv/api.h

@@ -52,6 +52,15 @@ struct gcv_context
 };
 
 
+typedef int (*gcv_context_bulk_begin_func_t)(
+	struct gcv_context *context,
+	void *client_data);
+
+typedef int (*gcv_context_bulk_end_func_t)(
+	struct gcv_context *context,
+	void *client_data);
+
+
 /**
  * Initialize a conversion context.
  */
@@ -68,6 +77,19 @@ GCV_EXPORT void
 gcv_context_destroy(struct gcv_context *cxt);
 
 
+/**
+ * Register callbacks used by mutating conversions to bracket bulk database
+ * changes.  This lets embedding applications suppress per-object live
+ * reconciliation while a reader or in-place filter is importing/updating many
+ * objects, then perform one final refresh.
+ */
+GCV_EXPORT void
+gcv_context_bulk_callbacks_set(struct gcv_context *cxt,
+			       gcv_context_bulk_begin_func_t begin_func,
+			       gcv_context_bulk_end_func_t end_func,
+			       void *client_data);
+
+
 enum gcv_tessellation_algorithm {
     GCV_TESS_DEFAULT = 0,
     GCV_TESS_BOTTESS,

include/ged.h

@@ -46,14 +46,17 @@
 
 #include "common.h"
 
-#include "bv/defines.h"
+#include "bsg/defines.h"
 #include "raytrace.h"
 #include "analyze.h"
 #include "ged/defines.h"
 #include "ged/version.h"
 #include "ged/database.h"
+#include "ged/db_index.h"
+#include "ged/event_txn.h"
 #include "ged/commands.h"
 #include "ged/objects.h"
+#include "ged/selection_state.h"
 #include "ged/view.h"
 #include "ged/debug.h"
 
@@ -111,7 +114,7 @@ GED_EXPORT extern int ged_help(struct ged *gedp, int argc, const char *argv[]);
  * }                   |
  *                     |
  * struct geometry { <-'
- *   display lists
+ *   drawn scene records
  *   directory *
  *   update()
  * }

include/ged/CMakeLists.txt

@@ -1,10 +1,14 @@
 set(
   ged_headers
+  bsg_ged_draw.h
   commands.h
   database.h
+  db_index.h
   debug.h
   defines.h
+  event_txn.h
   objects.h
+  selection_state.h
   version.h
   view.h
 )

include/ged/bsg_ged_draw.h

@@ -0,0 +1,604 @@
+/*                B S G _ G E D _ D R A W . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup ged_view
+ *
+ * @brief
+ * BSG-backed GED draw-scene API.
+ *
+ * Modern callers should treat the draw set as semantic records:
+ *   - ged_draw_shape_ref / ged_draw_group_ref are stable handles for the
+ *     current draw-scene revision.
+ *   - ged_draw_shape_record / ged_draw_group_record expose path identity,
+ *     draw source/style, visibility, and highlight state without requiring
+ *     callers to inspect BSG node layout.
+ *
+ * The BSG tree remains the private implementation used by the GED/BSG bridge.
+ * Installed GED callers should not need BSG node pointers to query or update
+ * the draw scene.
+ *
+ * Drawn database objects are keyed by struct db_full_path.  String path
+ * formatting is available for logging/UI, but graph mutation APIs use the
+ * structured path form.
+ */
+/** @{ */
+/* @file ged/bsg_ged_draw.h */
+
+#ifndef GED_BSG_GED_DRAW_H
+#define GED_BSG_GED_DRAW_H
+
+#include "common.h"
+
+#include "vmath.h"
+#include "bu/list.h"
+#include "bu/ptbl.h"
+#include "bu/vls.h"
+#include "bsg/draw_intent.h"
+#include "bsg/interaction.h"
+#include "ged/defines.h"
+
+/* Forward declaration to keep the include surface narrow.  Callers that
+ * actually use the db_full_path variants will already be including
+ * "raytrace.h" or "rt/db_fullpath.h" anyway. */
+struct db_full_path;
+struct db_i;
+struct bn_tol;
+struct bg_tess_tol;
+struct bsg_view;
+struct bsg_mesh_lod_context;
+
+typedef enum ged_draw_stale_reason {
+    GED_DRAW_STALE_NONE = 0,
+    GED_DRAW_STALE_SOURCE_CHANGED,
+    GED_DRAW_STALE_VIEW_INPUT_CHANGED,
+    GED_DRAW_STALE_SETTINGS_CHANGED,
+    GED_DRAW_STALE_FORCED,
+    GED_DRAW_STALE_UPDATE_FAILED
+} ged_draw_stale_reason;
+
+typedef enum ged_draw_transaction_kind {
+    GED_DRAW_TXN_NONE = 0,
+    GED_DRAW_TXN_DRAW,
+    GED_DRAW_TXN_ERASE,
+    GED_DRAW_TXN_ERASE_PREFIX,
+    GED_DRAW_TXN_REDRAW,
+    GED_DRAW_TXN_VISIBILITY,
+    GED_DRAW_TXN_HIGHLIGHT,
+    GED_DRAW_TXN_MATERIAL_CHANGED,
+    GED_DRAW_TXN_REFRESH_MATERIAL_COLORS,
+    GED_DRAW_TXN_TRANSPARENCY,
+    GED_DRAW_TXN_DEFAULT_DRAW_MODE,
+    GED_DRAW_TXN_STALE_SOURCE,
+    GED_DRAW_TXN_SOURCE_UPDATED,
+    GED_DRAW_TXN_SOURCE_RENAMED,
+    GED_DRAW_TXN_SOURCE_REFERENCES_REMOVED,
+    GED_DRAW_TXN_CLEAR,
+    GED_DRAW_TXN_CLEAR_SCOPE,
+    GED_DRAW_TXN_TEARDOWN
+} ged_draw_transaction_kind;
+
+struct ged_draw_transaction {
+    ged_draw_transaction_kind kind;
+    const char *path;                 /**< borrowed command-facing path/name */
+    const char *new_path;             /**< optional borrowed replacement path/name */
+    const char **paths;               /**< optional borrowed draw path array */
+    int path_count;                   /**< entries in @p paths */
+    const struct db_full_path *dfp;   /**< optional structured path target */
+    struct bsg_view *view;            /**< optional view scope for view-aware transactions */
+    int mode;                         /**< optional draw-mode filter; <0 means all modes */
+    const struct bsg_appearance_settings *appearance; /**< optional borrowed draw settings */
+    int autoview;                     /**< draw transaction may update view bounds */
+    double value;                     /**< visibility/highlight/transparency/mode */
+    ged_draw_stale_reason stale_reason;
+    int removed;
+    int redraw;
+};
+
+struct ged_draw_transaction_result {
+    int status;                       /**< >=0 success/count, <0 error */
+    int affected_groups;
+    int affected_shapes;
+    int stale_count;
+    int redrawn_count;
+    int error_count;
+    uint64_t scene_revision_before;
+    uint64_t scene_revision_after;
+    struct bu_vls names;              /**< affected user-facing target names */
+    struct bu_vls errors;             /**< diagnostic details */
+};
+
+typedef uintptr_t ged_draw_observer_token;
+typedef void (*ged_draw_transaction_observer_func_t)(
+	struct ged *gedp,
+	const struct ged_draw_transaction *txn,
+	const struct ged_draw_transaction_result *result,
+	void *client_data);
+
+__BEGIN_DECLS
+
+typedef struct ged_draw_shape_ref {
+    uintptr_t token;
+    uint64_t scene_revision;
+} ged_draw_shape_ref;
+
+typedef struct ged_draw_group_ref {
+    uintptr_t token;
+    uint64_t scene_revision;
+} ged_draw_group_ref;
+
+#define GED_DRAW_SHAPE_REF_NULL_INIT {0, 0}
+#define GED_DRAW_GROUP_REF_NULL_INIT {0, 0}
+
+#ifdef __cplusplus
+#  define GED_DRAW_SHAPE_REF_NULL ged_draw_shape_ref{0, 0}
+#  define GED_DRAW_GROUP_REF_NULL ged_draw_group_ref{0, 0}
+#else
+#  define GED_DRAW_SHAPE_REF_NULL ((ged_draw_shape_ref){0, 0})
+#  define GED_DRAW_GROUP_REF_NULL ((ged_draw_group_ref){0, 0})
+#endif
+
+struct ged_draw_shape_record {
+    ged_draw_shape_ref ref;
+    ged_draw_group_ref group;
+    const struct db_full_path *fullpath; /**< borrowed; valid while draw scene is unchanged */
+    const char *display_name;            /**< borrowed */
+    const char *leaf_name;               /**< borrowed */
+    unsigned long long path_hash;
+    int visible;
+    int highlighted;
+    int selected;
+    int evaluated_region;
+    int stale;
+    const char *stale_reason;
+    uint64_t source_revision;
+    uint64_t inputs_revision;
+    uint64_t realized_source_revision;
+    uint64_t realized_inputs_revision;
+    uint64_t drawn_revision;
+    fastf_t transparency;
+    bsg_draw_mode draw_mode;
+    int line_width;
+    point_t center;
+};
+
+struct ged_draw_group_record {
+    ged_draw_group_ref ref;
+    const char *path;                    /**< borrowed */
+    struct bsg_view *view;               /**< borrowed; NULL for view-independent groups */
+    bsg_draw_mode draw_mode;
+    fastf_t transparency;
+    int visible;
+    int is_overlay;
+    int is_view_scope;
+    int in_view_scope;
+    int is_view_source;
+    int is_local_source;
+    int shape_count;
+};
+
+GED_EXPORT extern struct ged_draw_transaction
+ged_draw_transaction_make(ged_draw_transaction_kind kind, const char *path);
+
+GED_EXPORT extern struct ged_draw_transaction
+ged_draw_transaction_make_value(ged_draw_transaction_kind kind,
+				const char *path,
+				double value);
+
+GED_EXPORT extern void
+ged_draw_transaction_result_init(struct ged_draw_transaction_result *result);
+
+GED_EXPORT extern void
+ged_draw_transaction_result_free(struct ged_draw_transaction_result *result);
+
+GED_EXPORT extern int
+ged_draw_apply_transaction(struct ged *gedp,
+			   const struct ged_draw_transaction *txn,
+			   struct ged_draw_transaction_result *result);
+
+/**
+ * Subscribe to post-transaction draw-state events.
+ *
+ * Observers are called synchronously after a successful draw transaction has
+ * reconciled libged draw state and populated a stable
+ * ged_draw_transaction_result.  The returned token may be passed to
+ * ged_draw_observer_remove(); 0 indicates registration failure.
+ */
+GED_EXPORT extern ged_draw_observer_token
+ged_draw_observer_add(struct ged *gedp,
+		      ged_draw_transaction_observer_func_t func,
+		      void *client_data);
+
+/**
+ * Remove a draw-state observer.  Safe to call from inside an observer callback.
+ * Returns 1 when a live observer was removed, 0 otherwise.
+ */
+GED_EXPORT extern int
+ged_draw_observer_remove(struct ged *gedp, ged_draw_observer_token token);
+
+GED_EXPORT extern int
+ged_draw_mark_database_change(struct ged *gedp,
+			      const char *path,
+			      ged_draw_stale_reason reason);
+
+GED_EXPORT extern int
+ged_draw_apply_database_update(struct ged *gedp,
+			       const char *path,
+			       int removed,
+			       int redraw);
+
+GED_EXPORT extern const char *
+ged_draw_stale_reason_name(ged_draw_stale_reason reason);
+
+/**
+ * Return non-zero when @p gedp has an initialized draw scene.
+ */
+GED_EXPORT extern int
+ged_draw_scene_available(struct ged *gedp);
+
+/**
+ * Structured-path convenience wrappers for common command operations.
+ */
+GED_EXPORT extern int
+ged_draw_apply_erase_path(struct ged *gedp,
+			  const struct db_full_path *dfp);
+
+GED_EXPORT extern int
+ged_draw_apply_erase_path_prefix(struct ged *gedp,
+				 const struct db_full_path *dfp);
+
+/**
+ * Return the current default draw mode used by draw commands that do not
+ * specify an explicit render style override.
+ */
+GED_EXPORT extern bsg_draw_mode
+ged_draw_default_mode(const struct ged *gedp);
+
+/**
+ * Erase from @p gedp's drawn scene the entry whose path equals @p dfp.
+ * When a scene group's path is a strict ancestor of the erase path, the
+ * matching sub-tree is removed without disturbing sibling sub-groups.
+ */
+GED_EXPORT extern void
+ged_draw_erase_path(struct ged *gedp,
+			     const struct db_full_path *dfp);
+
+/**
+ * Erase from @p gedp's drawn-object set every scene object whose path
+ * contains @p name as one of its directory components.
+ *
+ * This is used when a database object is renamed or deleted and all drawn
+ * references to that name must be removed.
+ */
+GED_EXPORT extern void
+ged_draw_erase_name(struct ged *gedp, const char *name);
+
+/**
+ * Erase every drawn scene object whose path has @p dfp as a prefix subset.
+ */
+GED_EXPORT extern void
+ged_draw_erase_path_prefix(struct ged *gedp,
+			       const struct db_full_path *dfp);
+
+/**
+ * Compute the axis-aligned bounding box of the visible drawn scene in
+ * @p gedp's active view set.  When @p pflag is zero, non-database overlay
+ * records are excluded.
+ * Returns 1 if the result is empty (no contributing objects), 0 otherwise.
+ *
+ * The bounds are returned in model coordinates.
+ */
+GED_EXPORT extern int
+ged_draw_bounds(struct ged *gedp, vect_t *min, vect_t *max,
+		    int pflag);
+
+/**
+ * Set the draw-scene highlight state for every drawn shape.  A non-zero
+ * @p highlighted value asserts highlight state; zero clears it.
+ */
+GED_EXPORT extern void
+ged_draw_set_highlight_state(struct ged *gedp, int highlighted);
+
+/**
+ * Set highlight state on all draw shapes whose database full path begins with
+ * @p path[0..path_pos].  This is the semantic operation behind MGED matrix
+ * path picking, where multiple rendered shapes can share the same editable
+ * path prefix.
+ *
+ * Returns the number of matching shape records.
+ */
+GED_EXPORT extern int
+ged_draw_set_highlighted_path_prefix(struct ged *gedp,
+				     const struct db_full_path *path,
+				     size_t path_pos,
+				     int highlighted);
+
+/**
+ * Return the highlight-state revision counter.  Bumped on every transition
+ * of the highlighted draw ref.  Cache a snapshot and compare to detect
+ * "highlight may have changed since I last looked" cheaply.
+ */
+GED_EXPORT extern uint64_t
+ged_draw_highlight_revision(const struct ged *gedp);
+
+/**
+ * Return the material revision counter.  The counter is incremented by
+ * ged_draw_bump_material_revision() whenever the material/color table changes.
+ * ged_draw_refresh_material_colors() does NOT increment the counter; it only
+ * stamps per-shape color revisions.  Callers that cache per-shape color
+ * data can compare a saved snapshot to detect when a recolor sweep is needed.
+ */
+GED_EXPORT extern uint64_t
+ged_draw_material_revision(const struct ged *gedp);
+
+/**
+ * Bump the material revision counter.
+ *
+ * Call this after any operation that changes the effective material or
+ * color table (e.g. 'color', 'mater', 'rmater', 'edmater') so that the
+ * next ged_draw_refresh_material_colors() call recolors shapes that are
+ * now stale.
+ */
+GED_EXPORT extern void
+ged_draw_bump_material_revision(struct ged *gedp);
+
+/**
+ * Refresh per-object base color from the dbip's region/material table
+ * (mater_struct chain) for every drawn scene object whose color stamp is
+ * stale relative to the material revision counter.  Shapes that
+ * were already colored since the last material-change event are skipped.
+ *
+ * Callers must invoke ged_draw_bump_material_revision() before this function
+ * to signal that a material change occurred; without that bump, successive
+ * calls will skip all already-stamped shapes.
+ */
+GED_EXPORT extern void
+ged_draw_refresh_material_colors(struct ged *gedp);
+
+/**
+ * Return the current draw-scene structural revision as an unsigned long long.
+ * Returns 0 when the scene is unavailable or after a clear operation.
+ *
+ * Prefer ged_draw_scene_revision() for new code that only needs change
+ * detection.
+ */
+GED_EXPORT extern unsigned long long
+ged_draw_scene_hash(struct ged *gedp);
+
+/**
+ * Return the raw structural revision counter for @p gedp's draw tree.
+ * The counter is incremented on every structural mutation (group/shape
+ * addition or removal) and reset to 0 by ged_draw_clear().  Returns
+ * 0 when no objects have been drawn since the last zap (or ever).
+ *
+ * Callers that need to detect "drawn set changed" cheaply should compare
+ * snapshots of this value rather than recomputing a content hash.
+ */
+GED_EXPORT extern uint64_t
+ged_draw_scene_revision(struct ged *gedp);
+
+GED_EXPORT extern int
+ged_draw_shape_ref_is_null(ged_draw_shape_ref ref);
+
+GED_EXPORT extern int
+ged_draw_group_ref_is_null(ged_draw_group_ref ref);
+
+GED_EXPORT extern int
+ged_draw_shape_record_get(struct ged *gedp,
+			  ged_draw_shape_ref ref,
+			  struct ged_draw_shape_record *out);
+
+GED_EXPORT extern int
+ged_draw_group_record_get(struct ged *gedp,
+			  ged_draw_group_ref ref,
+			  struct ged_draw_group_record *out);
+
+GED_EXPORT extern void
+ged_draw_foreach_group_record(struct ged *gedp,
+			      int (*cb)(const struct ged_draw_group_record *rec,
+					void *userdata),
+			      void *userdata);
+
+GED_EXPORT extern void
+ged_draw_foreach_shape_record(struct ged *gedp,
+			      int (*cb)(const struct ged_draw_shape_record *rec,
+					void *userdata),
+			      void *userdata);
+
+GED_EXPORT extern ged_draw_shape_ref
+ged_draw_first_shape_ref(struct ged *gedp);
+
+GED_EXPORT extern ged_draw_shape_ref
+ged_draw_shape_ref_at(struct ged *gedp, int idx);
+
+GED_EXPORT extern int
+ged_draw_shape_ref_index(struct ged *gedp, ged_draw_shape_ref ref);
+
+GED_EXPORT extern ged_draw_shape_ref
+ged_draw_advance_shape_ref(struct ged *gedp, ged_draw_shape_ref ref, int delta);
+
+GED_EXPORT extern ged_draw_group_ref
+ged_draw_group_ref_of_shape(struct ged *gedp, ged_draw_shape_ref ref);
+
+GED_EXPORT extern void
+ged_draw_set_highlighted_shape_ref(struct ged *gedp, ged_draw_shape_ref ref);
+
+GED_EXPORT extern int
+ged_draw_shape_set_highlighted(struct ged *gedp, ged_draw_shape_ref ref, int highlighted);
+
+GED_EXPORT extern int
+ged_draw_shape_ref_get_color(struct ged *gedp, ged_draw_shape_ref ref, unsigned char rgb[3]);
+
+GED_EXPORT extern int
+ged_draw_shape_ref_set_color(struct ged *gedp, ged_draw_shape_ref ref, const unsigned char rgb[3]);
+
+GED_EXPORT extern int
+ged_draw_shape_ref_last_point(struct ged *gedp,
+			      ged_draw_shape_ref ref,
+			      point_t out);
+
+GED_EXPORT extern int
+ged_draw_shape_ref_translate_geometry(struct ged *gedp,
+				      ged_draw_shape_ref ref,
+				      const vect_t xlate);
+
+GED_EXPORT extern int
+ged_draw_shape_ref_set_center(struct ged *gedp,
+			      ged_draw_shape_ref ref,
+			      const point_t center);
+
+GED_EXPORT extern int
+ged_draw_shape_ref_geometry_clear(struct ged *gedp,
+				  ged_draw_shape_ref ref);
+
+GED_EXPORT extern int
+ged_draw_shape_ref_update_bounds_from_geometry(struct ged *gedp,
+					       ged_draw_shape_ref ref,
+					       int *bad_cmd);
+
+GED_EXPORT extern int
+ged_draw_shape_ref_publish_primitive_wireframe(struct ged *gedp,
+					       ged_draw_shape_ref ref,
+					       struct rt_db_internal *ip,
+					       const struct bg_tess_tol *ttol,
+					       const struct bn_tol *tol,
+					       struct bsg_view *v,
+					       int adaptive);
+
+GED_EXPORT extern ged_draw_shape_ref
+ged_draw_highlighted_shape_ref(const struct ged *gedp);
+
+GED_EXPORT extern ged_draw_shape_ref
+ged_draw_highlight_shape_ref_by_name(struct ged *gedp, const char *name);
+
+GED_EXPORT extern struct bsg_interaction_record *
+ged_draw_shape_interaction_record(struct ged *gedp,
+				  ged_draw_shape_ref ref,
+				  bsg_interaction_kind kind);
+
+/**
+ * Returns 1 if @p gedp has at least one drawn shape, 0 otherwise.
+ */
+GED_EXPORT extern int
+ged_draw_has_shapes(struct ged *gedp);
+
+/**
+ * Report whether @p path is represented in the retained draw scene.
+ *
+ * Return values match qged/MGED drawn-state conventions:
+ *   - 0: path is not drawn
+ *   - 1: path is fully drawn
+ *   - 2: path is partially drawn
+ *
+ * The query is answered from retained draw records.  When hierarchy coverage
+ * must be distinguished from a partial draw, the no-index fallback walks only
+ * @p path's database subtree and compares its leaf paths to active retained
+ * shapes.  Pass @p mode < 0 to query all draw modes.
+ */
+GED_EXPORT extern int
+ged_draw_path_state(struct ged *gedp,
+		    struct bsg_view *v,
+		    const char *path,
+		    int mode);
+
+/**
+ * Return non-zero when @p rec belongs to the drawable database scene for
+ * @p v.  Shared draw groups match non-independent views; independent views
+ * match only groups in their private view scope.  Passing NULL for @p v
+ * queries only shared draw groups.
+ *
+ * This helper answers view-scope membership only.  Callers that list renderable
+ * database paths must still check record visibility, overlay status, and draw
+ * mode as appropriate.
+ */
+GED_EXPORT extern int
+ged_draw_group_record_in_view(const struct ged_draw_group_record *rec,
+			      struct bsg_view *v);
+
+/**
+ * Append retained draw paths to @p result and return the number appended.
+ *
+ * When @p expanded is zero, paths are draw-intent/group paths suitable for
+ * command-level listings such as "who" and render-script replay.  When
+ * @p expanded is non-zero, paths are realized leaf shape paths.  Overlay,
+ * hidden, empty, and out-of-view records are omitted.  Pass @p mode < 0 to list
+ * all draw modes.
+ */
+GED_EXPORT extern size_t
+ged_draw_list_paths(struct ged *gedp,
+		    struct bsg_view *v,
+		    int mode,
+		    int expanded,
+		    struct bu_vls *result);
+
+/**
+ * Return non-zero if command-visible drawn database paths exist for @p v and
+ * @p mode.  This uses the same visibility/view/overlay filtering as
+ * ged_draw_list_paths(..., expanded=0) without formatting or sorting paths.
+ */
+GED_EXPORT extern int
+ged_draw_has_paths(struct ged *gedp,
+		   struct bsg_view *v,
+		   int mode);
+
+/**
+ * Returns the first drawn scene object in display order, or NULL if
+ * none are drawn.
+ */
+GED_EXPORT extern int
+ged_draw_shape_count(struct ged *gedp);
+
+/**
+ * Erase all scene groups from @p gedp's drawn-object set, destroying vlists
+ * and freeing all associated scene objects.
+ * This is the "zap" operation.
+ */
+GED_EXPORT extern void
+ged_draw_clear(struct ged *gedp);
+
+/**
+ * Erase database draw groups in one draw scope.  Passing NULL for @p v clears
+ * shared database draw groups.  Passing an independent view clears that view's
+ * independent database draw scope.
+ *
+ * Returns the number of top-level retained draw groups removed.
+ */
+GED_EXPORT extern int
+ged_draw_clear_view(struct ged *gedp, struct bsg_view *v);
+
+/**
+ * Return 1 if any scene groups exist (i.e., something is drawn), 0 if the
+ * display is empty.
+ */
+GED_EXPORT extern int
+ged_draw_has_groups(struct ged *gedp);
+
+__END_DECLS
+
+#endif /* GED_BSG_GED_DRAW_H */
+
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/ged/commands.h

@@ -35,6 +35,8 @@
 
 __BEGIN_DECLS
 
+struct bu_opt_validate_result;
+
 /** @addtogroup ged_plugins */
 /** @{ */
 /** Execute plugin based command */
@@ -113,6 +115,22 @@ ged_cmd_completions(const char ***completions, const char *seed);
 GED_EXPORT extern int
 ged_geom_completions(const char ***completions, struct bu_vls *cprefix, struct db_i *dbip, const char *seed);
 
+/* Report whether a GED command has schema metadata available. */
+GED_EXPORT extern int
+ged_cmd_schema_exists(const char *cmd);
+
+/* Return JSON schema metadata for a GED command.  Caller must free with bu_free. */
+GED_EXPORT extern char *
+ged_cmd_schema_json(const char *cmd);
+
+/* Validate a GED command line against available schema metadata. */
+GED_EXPORT extern int
+ged_cmd_validate(struct ged *gedp, const char *input, size_t cursor_pos, struct bu_opt_validate_result *result);
+
+/* Complete the token at cursor_pos using schema metadata and existing fallbacks. */
+GED_EXPORT extern int
+ged_cmd_complete(const char ***completions, struct bu_vls *prefix, struct ged *gedp, const char *input, size_t cursor_pos);
+
 
 /**
  * Use bu_editor to set up an editor for use with GED
@@ -152,9 +170,6 @@ GED_EXPORT extern int ged_inside_internal(struct ged *gedp,
 					  char *o_name);
 
 
-GED_EXPORT void draw_scene(struct bv_scene_obj *s, struct bview *v);
-
-
 /** @} */
 
 

include/ged/db_index.h

@@ -0,0 +1,258 @@
+/*                       D B _ I N D E X . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this file; see the file named COPYING for more information.
+ */
+/** @addtogroup ged_database
+ *
+ * @brief Explicit GED database hierarchy/index query API.
+ *
+ * The `.g` database remains authoritative.  The GED database index is a
+ * derived, rebuildable service owned by a `struct ged` context and used by
+ * drawing, selection, editing, and application adapters for explicit
+ * object/instance/path questions.
+ *
+ * This interface deliberately exposes records and queries, not implementation
+ * containers.  Callers must not rely on private maps, Qt item storage, or any
+ * particular backend layout.
+ *
+ * Complexity expectations:
+ *   - object lookup by id is expected O(1);
+ *   - direct child count/row lookup is expected O(1) after the parent object
+ *     has been indexed;
+ *   - direct object-use count/row lookup is expected O(1) after the child
+ *     object has been indexed;
+ *   - affected-path queries are expected O(number of returned affected paths
+ *     plus their depth), using reverse object-use records;
+ *   - top-object listing is O(number of top objects), with cyclic extras
+ *     requiring bounded traversal of known comb-child records;
+ *   - path printing and hashing are O(path depth);
+ *   - APIs here must not require expansion of every possible full path.
+ */
+/** @{ */
+/** @file ged/db_index.h */
+
+#ifndef GED_DB_INDEX_H
+#define GED_DB_INDEX_H
+
+#include "common.h"
+
+#include <stddef.h>
+
+#include "bu/vls.h"
+#include "ged/defines.h"
+
+struct directory;
+
+typedef unsigned long long ged_db_index_id;
+
+#define GED_DB_INDEX_REFRESH_DB_CHANGE   0x01
+#define GED_DB_INDEX_REFRESH_VIEW_CHANGE 0x02
+
+#define GED_DB_INDEX_OBJECT_CHANGED 0
+#define GED_DB_INDEX_OBJECT_ADDED   1
+#define GED_DB_INDEX_OBJECT_REMOVED 2
+
+struct ged_db_index_record {
+    ged_db_index_id id;        /**< object or unique child-instance id */
+    ged_db_index_id object_id; /**< canonical object id for duplicate instances */
+    const char *name;          /**< borrowed display/name string */
+    struct directory *dp;      /**< borrowed directory pointer when valid */
+    int valid;                 /**< non-zero when id is known to the index */
+    int is_instance;           /**< non-zero when id names a duplicate child instance */
+    int is_comb;               /**< non-zero when the canonical object is a comb */
+    size_t child_count;        /**< direct child instances, 0 for leaves/invalid refs */
+};
+
+struct ged_db_index_child {
+    struct ged_db_index_record record;
+    int bool_op;               /**< DB_OP_* value from raytrace.h/db_op_t */
+    size_t row;                /**< row in index-presented child order */
+};
+
+struct ged_db_index_use {
+    struct ged_db_index_record parent; /**< direct comb parent using child */
+    struct ged_db_index_record child;  /**< child instance record at parent row */
+    int bool_op;                       /**< DB_OP_* value from raytrace.h/db_op_t */
+    size_t child_row;                  /**< row of child in parent */
+};
+
+__BEGIN_DECLS
+
+/**
+ * Return non-zero when @p gedp has an initialized database-index service.
+ *
+ * Callers should use this only as a capability check, not to infer backend
+ * layout.
+ */
+GED_EXPORT extern int
+ged_db_index_available(struct ged *gedp);
+
+/**
+ * Reconcile/rebuild the derived index from the current database state.
+ *
+ * Return value is backend-specific non-negative work/revision information, or
+ * 0 when no backend/index is available.
+ */
+GED_EXPORT extern unsigned long long
+ged_db_index_refresh(struct ged *gedp);
+
+/**
+ * Reconcile/rebuild the derived index and return backend change flags.
+ *
+ * This is for migration callers that need refresh classification such as
+ * GED_DB_INDEX_REFRESH_VIEW_CHANGE.  A zero return means the refresh found no
+ * observable change flags or no backend/index is available.
+ */
+GED_EXPORT extern unsigned long long
+ged_db_index_refresh_flags(struct ged *gedp);
+
+/**
+ * Queue a database object change for the next index refresh.
+ *
+ * This is the public migration bridge for librt dbi_changed_t callbacks.
+ * It invalidates derived per-object caches and records the changed object
+ * using one of GED_DB_INDEX_OBJECT_CHANGED, GED_DB_INDEX_OBJECT_ADDED, or
+ * GED_DB_INDEX_OBJECT_REMOVED.  The actual database-index reconciliation and
+ * nref update happen when ged_db_index_refresh() or
+ * ged_db_index_refresh_flags() is called.
+ *
+ * Returns 1 when the change was queued, 0 when no index backend/object was
+ * available or @p change_kind was not recognized.
+ */
+GED_EXPORT extern int
+ged_db_index_note_object_change(struct ged *gedp,
+				struct directory *dp,
+				int change_kind);
+
+/**
+ * Queue a database object change by name for the next index refresh.
+ *
+ * This is used by semantic command events when a live directory pointer is not
+ * available, especially after removal or rename.  For changed/added objects the
+ * current directory entry is looked up and queued through
+ * ged_db_index_note_object_change(); removed names are recorded directly.
+ */
+GED_EXPORT extern int
+ged_db_index_note_object_name_change(struct ged *gedp,
+				     const char *name,
+				     int change_kind);
+
+GED_EXPORT extern int
+ged_db_index_record_get(struct ged *gedp,
+			ged_db_index_id id,
+			struct ged_db_index_record *record);
+
+GED_EXPORT extern size_t
+ged_db_index_tops(struct ged *gedp,
+		  int include_cyclic,
+		  ged_db_index_id *ids,
+		  size_t capacity);
+
+GED_EXPORT extern size_t
+ged_db_index_child_count(struct ged *gedp,
+			 ged_db_index_id parent_id);
+
+GED_EXPORT extern int
+ged_db_index_child_at(struct ged *gedp,
+		      ged_db_index_id parent_id,
+		      size_t row,
+		      struct ged_db_index_child *child);
+
+GED_EXPORT extern size_t
+ged_db_index_object_use_count(struct ged *gedp,
+			      ged_db_index_id object_id);
+
+GED_EXPORT extern int
+ged_db_index_object_use_at(struct ged *gedp,
+			   ged_db_index_id object_id,
+			   size_t row,
+			   struct ged_db_index_use *use);
+
+/**
+ * Count indexed hierarchy paths affected by a change to @p object_id.
+ *
+ * The count is derived from reverse object-use records and includes one row
+ * per distinct indexed path ending in @p object_id or one of its duplicate
+ * child instance ids.  Passing a duplicate instance id canonicalizes to the
+ * underlying object.  @p max_depth bounds returned path depth when non-zero.
+ */
+GED_EXPORT extern size_t
+ged_db_index_affected_path_count(struct ged *gedp,
+				 ged_db_index_id object_id,
+				 size_t max_depth);
+
+/**
+ * Copy one indexed affected path for @p object_id.
+ *
+ * Returns the full path depth for @p row, or 0 when the row is unavailable.
+ * When @p ids is non-NULL, up to @p capacity ids are copied.  Callers may pass
+ * NULL/0 first to query the required depth, then call again with storage.
+ */
+GED_EXPORT extern size_t
+ged_db_index_affected_path_at(struct ged *gedp,
+			      ged_db_index_id object_id,
+			      size_t row,
+			      ged_db_index_id *ids,
+			      size_t capacity,
+			      size_t max_depth);
+
+GED_EXPORT extern int
+ged_db_index_valid_id(struct ged *gedp, ged_db_index_id id);
+
+/**
+ * Resolve a database path string into database-index path ids.
+ *
+ * On success, returns the full number of ids in the resolved path.  When
+ * @p ids is non-NULL, up to @p capacity ids are copied into it; callers may
+ * pass NULL/0 first to query the required length.  Returns 0 when the path is
+ * empty, invalid, or no backend is available to resolve indexed paths.
+ */
+GED_EXPORT extern size_t
+ged_db_index_path_resolve(struct ged *gedp,
+			  const char *path,
+			  ged_db_index_id *ids,
+			  size_t capacity);
+
+GED_EXPORT extern int
+ged_db_index_path_print(struct ged *gedp,
+			struct bu_vls *out,
+			const ged_db_index_id *path,
+			size_t path_len,
+			size_t max_len,
+			int verbose);
+
+GED_EXPORT extern ged_db_index_id
+ged_db_index_path_hash(struct ged *gedp,
+		       const ged_db_index_id *path,
+		       size_t path_len,
+		       size_t max_len);
+
+__END_DECLS
+
+#endif /* GED_DB_INDEX_H */
+
+/** @} */
+
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/ged/defines.h

@@ -33,10 +33,10 @@
 #include "bu/list.h"
 #include "bu/process.h"
 #include "bu/vls.h"
-#include "bv/defines.h"
+#include "bsg/defines.h"
 #include "rt/search.h"
-#include "bv/defines.h"
-#include "bv/lod.h"
+#include "bsg/defines.h"
+#include "bsg/lod.h"
 #include "dm/fbserv.h" // for fbserv_obj
 #include "rt/wdb.h" // for struct rt_wdb
 
@@ -54,9 +54,10 @@
 #endif
 
 #define GED_NULL ((struct ged *)0)
+/* GED_DISPLAY_LIST_NULL is deprecated — use NULL directly */
 #define GED_DISPLAY_LIST_NULL ((struct display_list *)0)
 #define GED_DRAWABLE_NULL ((struct ged_drawable *)0)
-#define GED_VIEW_NULL ((struct bview *)0)
+#define GED_VIEW_NULL ((struct bsg_view *)0)
 
 #define GED_RESULT_NULL ((void *)0)
 
@@ -82,9 +83,6 @@ typedef int (*ged_func_ptr)(struct ged *, int, const char *[]);
 /* Callback related definitions */
 typedef void (*ged_io_func_t)(void *, int);
 typedef void (*ged_refresh_func_t)(void *);
-typedef void (*ged_create_vlist_solid_func_t)(void *, struct bv_scene_obj *);
-typedef void (*ged_create_vlist_display_list_func_t)(void *, struct display_list *);
-typedef void (*ged_destroy_vlist_func_t)(void *, unsigned int, int);
 struct ged_callback_state;
 
 /**
@@ -159,15 +157,14 @@ struct ged {
     struct ged_impl             *i;
     struct bu_vls               go_name;
     struct db_i                 *dbip;
-    void			*dbi_state; // for experimental state work
 
     /*************************************************************/
-    /* Information pertaining to views and view objects .        */
+    /* Information pertaining to views and view-scoped drawing state. */
     /*************************************************************/
     /* The current view */
-    struct bview		*ged_gvp;
+    struct bsg_view		*ged_gvp;
     /* The full set of views associated with this ged object */
-    struct bview_set            ged_views;
+    struct bsg_view_set            ged_views;
     /* Sometimes applications will supply GED views, and sometimes GED commands
      * may create views.  In the latter case, ged_close will also need to free
      * the views.  We define a container to hold those views that libged is
@@ -176,7 +173,7 @@ struct ged {
     struct bu_ptbl              ged_free_views;
 
     /* Drawing data associated with this .g file */
-    struct bv_mesh_lod_context  *ged_lod;
+    struct bsg_mesh_lod_context  *ged_lod;
 
 
     void                        *u_data; /**< @brief User data associated with this ged instance */
@@ -198,8 +195,6 @@ struct ged {
     struct bu_vls		*ged_result_str;
     struct ged_results          *ged_results;
 
-    struct bu_ptbl              free_solids;
-
     char			*ged_output_script;		/**< @brief  script for use by the outputHandler */
 
     /* Old selection data containers used by joint and brep*/
@@ -236,10 +231,6 @@ struct ged {
     void (*ged_refresh_handler)(void *);	/**< @brief  function for handling refresh requests */
     void *ged_refresh_clientdata;	/**< @brief  client data passed to refresh handler */
     void (*ged_output_handler)(struct ged *, char *);	/**< @brief  function for handling output */
-    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 */
-    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  */
-    void (*ged_destroy_vlist_callback)(void *, unsigned int, int);	/**< @brief  function to call after freeing a vlist */
-    void *vlist_ctx;
 
     /* Handler functions for I/O communication with asynchronous subprocess commands.  There
      * are two opaque data structures at play here, with different scopes.  One is the "data"
@@ -280,11 +271,6 @@ struct ged {
     char terminal[MAXPATHLEN];
     struct bu_ptbl terminal_opts;
 
-    // The following is used instead of environment variables to select old or new
-    // command paths.  Primarily relates to the next generation drawing setup with
-    // view objects and the new BoT LoD logic.
-    int new_cmd_forms;
-
     // Container allowing calling apps to store pointers to their own data.
     // Ged init and free routines will set up and free the table, but the
     // contents are the apps responsibility.
@@ -360,7 +346,6 @@ GED_EXPORT extern int ged_clbk_exec(
 GED_EXPORT extern void ged_dm_ctx_set(struct ged *gedp, const char *dm_type, void *ctx);
 GED_EXPORT extern void *ged_dm_ctx_get(struct ged *gedp, const char *dm_type);
 
-
 /* accessor functions for ged_results - calling
  * applications should not work directly with the
  * internals of ged_results, which are not guaranteed

include/ged/event_txn.h

@@ -0,0 +1,259 @@
+/*                    E V E N T _ T X N . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this file; see the file named COPYING for more information.
+ */
+/** @addtogroup ged_database
+ *
+ * @brief GED semantic database mutation/reconciliation events.
+ *
+ * Commands publish post-mutation semantic database events here instead of
+ * performing draw, model, selection, or edit repair directly.  The event
+ * layer batches and coalesces local mutations, reconciles core GED services,
+ * then notifies application observers with stable post-reconcile state.
+ *
+ * Reconciliation delegates draw repair to the canonical ged_draw_transaction
+ * API.  Callers should treat these event records as semantic database events,
+ * not as draw transactions themselves.
+ */
+/** @{ */
+/** @file ged/event_txn.h */
+
+#ifndef GED_EVENT_TXN_H
+#define GED_EVENT_TXN_H
+
+#include "common.h"
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include "ged/defines.h"
+
+typedef enum ged_event_kind {
+    GED_EVENT_NONE = 0,
+    GED_EVENT_OBJECT_ADDED,
+    GED_EVENT_OBJECT_REMOVED,
+    GED_EVENT_OBJECT_RENAMED,
+    GED_EVENT_OBJECT_MODIFIED,
+    GED_EVENT_OBJECT_VISIBILITY_CHANGED,
+    GED_EVENT_COMB_TREE_CHANGED,
+    GED_EVENT_COMB_INSTANCE_REMOVED,
+    GED_EVENT_OBJECT_REFERENCES_REMOVED,
+    GED_EVENT_ATTRIBUTE_CHANGED,
+    GED_EVENT_MATERIAL_CHANGED,
+    GED_EVENT_BATCH_REBUILD,
+    GED_EVENT_DATABASE_METADATA_CHANGED
+} ged_event_kind;
+
+typedef enum ged_event_observer_phase {
+    GED_EVENT_OBSERVER_INTERNAL = 0,
+    GED_EVENT_OBSERVER_POST_RECONCILE = 1
+} ged_event_observer_phase;
+
+typedef uintptr_t ged_event_observer_token;
+
+struct ged_event {
+    ged_event_kind kind;
+    const char *name;        /**< primary object/path name, borrowed */
+    const char *new_name;    /**< replacement object/path name for rename, borrowed */
+    const char *parent_name; /**< parent comb/object for instance events, borrowed */
+    const char *child_name;  /**< child object/reference for instance events, borrowed */
+    const char *path;        /**< full affected instance path when known, borrowed */
+    int redraw;              /**< non-zero when modified sources should redraw now */
+};
+
+struct ged_event_txn_result {
+    int status;                       /**< >=0 success/count, <0 error */
+    size_t event_count;               /**< input event count */
+    size_t coalesced_event_count;     /**< events after exact duplicate coalescing */
+    int draw_status;                  /**< aggregate draw reconciliation status */
+    int db_index_status;              /**< aggregate database-index status */
+    int selection_status;             /**< aggregate selection reconciliation status */
+    uint64_t draw_scene_revision_before;
+    uint64_t draw_scene_revision_after;
+    struct bu_vls affected_names;     /**< affected user-facing names/paths */
+    struct bu_vls errors;             /**< diagnostic details */
+};
+
+typedef void (*ged_event_observer_func_t)(
+	struct ged *gedp,
+	const struct ged_event *events,
+	size_t event_count,
+	const struct ged_event_txn_result *result,
+	void *client_data);
+
+__BEGIN_DECLS
+
+GED_EXPORT extern int
+ged_event_txn_available(struct ged *gedp);
+
+GED_EXPORT extern int
+ged_event_txn_disable(struct ged *gedp);
+
+GED_EXPORT extern int
+ged_event_txn_enable(struct ged *gedp);
+
+/**
+ * Begin/end a bulk mutation/import transaction.  While a bulk transaction is
+ * active, per-command batches and published events are treated as evidence of
+ * database mutation, but interactive reconciliation is deferred.  The outermost
+ * end publishes one batch-rebuild event only when a live GED consumer is
+ * present.
+ */
+GED_EXPORT extern int
+ged_event_bulk_begin(struct ged *gedp);
+
+GED_EXPORT extern int
+ged_event_bulk_end(struct ged *gedp, struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_bulk_active(struct ged *gedp);
+
+GED_EXPORT extern int
+ged_event_txn_has_live_consumers(struct ged *gedp);
+
+/**
+ * Install/remove the GED-owned bridge from low-level librt database changed
+ * callbacks into GedEventTxn.  The bridge is a fallback source for database
+ * mutations that do not publish richer command semantic events directly.
+ */
+GED_EXPORT extern int
+ged_event_librt_callbacks_enable(struct ged *gedp);
+
+GED_EXPORT extern int
+ged_event_librt_callbacks_disable(struct ged *gedp);
+
+GED_EXPORT extern void
+ged_event_txn_result_init(struct ged_event_txn_result *result);
+
+GED_EXPORT extern void
+ged_event_txn_result_free(struct ged_event_txn_result *result);
+
+/**
+ * Begin/end a semantic event batch.  Events published while a batch is open
+ * are copied by the GED context and reconciled when the outermost batch ends.
+ */
+GED_EXPORT extern int
+ged_event_batch_begin(struct ged *gedp);
+
+GED_EXPORT extern int
+ged_event_batch_end(struct ged *gedp, struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_publish(struct ged *gedp,
+		  const struct ged_event *events,
+		  size_t event_count,
+		  struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_object_added(struct ged *gedp,
+			      const char *name,
+			      struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_object_removed(struct ged *gedp,
+				const char *name,
+				struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_object_renamed(struct ged *gedp,
+				const char *old_name,
+				const char *new_name,
+				struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_object_modified(struct ged *gedp,
+				 const char *name,
+				 int redraw,
+				 struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_object_visibility_changed(struct ged *gedp,
+					   const char *name,
+					   struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_comb_tree_changed(struct ged *gedp,
+				   const char *name,
+				   int redraw,
+				   struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_comb_instance_removed(struct ged *gedp,
+				       const char *parent_name,
+				       const char *child_name,
+				       const char *path,
+				       struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_object_references_removed(struct ged *gedp,
+					   const char *name,
+					   struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_object_reference_removed_from_parent(struct ged *gedp,
+						      const char *name,
+						      const char *parent_name,
+						      const char *path,
+						      struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_attribute_changed(struct ged *gedp,
+				   const char *name,
+				   int redraw,
+				   struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_material_changed(struct ged *gedp,
+				  struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_object_material_changed(struct ged *gedp,
+					 const char *name,
+					 struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_batch_rebuild(struct ged *gedp,
+			       struct ged_event_txn_result *result);
+
+GED_EXPORT extern int
+ged_event_notify_database_metadata_changed(struct ged *gedp,
+					   struct ged_event_txn_result *result);
+
+GED_EXPORT extern ged_event_observer_token
+ged_event_observer_add(struct ged *gedp,
+		       ged_event_observer_phase phase,
+		       ged_event_observer_func_t func,
+		       void *client_data);
+
+GED_EXPORT extern int
+ged_event_observer_remove(struct ged *gedp, ged_event_observer_token token);
+
+__END_DECLS
+
+#endif /* GED_EVENT_TXN_H */
+
+/** @} */
+
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/ged/selection_state.h

@@ -0,0 +1,197 @@
+/*                  S E L E C T I O N _ S T A T E . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this file; see the file named COPYING for more information.
+ */
+/** @addtogroup ged_view
+ *
+ * @brief GED semantic selection-state API.
+ *
+ * Selection state is owned by the GED context, not by Qt model items or view
+ * widgets.  Applications identify selected targets using database-index path
+ * ids and query semantic state such as selected paths, active ancestor paths,
+ * and parent-object highlighting.
+ *
+ * This service owns selection state directly.  Callers must not depend on
+ * private migration backends.
+ */
+/** @{ */
+/** @file ged/selection_state.h */
+
+#ifndef GED_SELECTION_STATE_H
+#define GED_SELECTION_STATE_H
+
+#include "common.h"
+
+#include <stddef.h>
+
+#include "ged/db_index.h"
+
+struct bu_vls;
+
+__BEGIN_DECLS
+
+/**
+ * Return non-zero when the GED context has an initialized selection service.
+ */
+GED_EXPORT extern int
+ged_selection_state_available(struct ged *gedp);
+
+/**
+ * Return the number of explicitly selected paths in @p set_name.
+ *
+ * A NULL or empty set name means the default selection set.
+ */
+GED_EXPORT extern size_t
+ged_selection_count(struct ged *gedp, const char *set_name);
+
+/**
+ * Append one selection-set name per line to @p out.
+ *
+ * The default set is implicit and is not included in the named-set listing.
+ * Returns the number of names appended.
+ */
+GED_EXPORT extern int
+ged_selection_list_set_names(struct ged *gedp, struct bu_vls *out);
+
+/**
+ * Append one selected database path per line for all sets matching
+ * @p set_pattern.  NULL or empty pattern means the default set.
+ *
+ * Returns the number of matching sets.
+ */
+GED_EXPORT extern int
+ged_selection_list_paths(struct ged *gedp,
+			 const char *set_pattern,
+			 struct bu_vls *out);
+
+GED_EXPORT extern int
+ged_selection_set_match_count(struct ged *gedp, const char *set_pattern);
+
+GED_EXPORT extern unsigned long long
+ged_selection_state_hash(struct ged *gedp, const char *set_name);
+
+GED_EXPORT extern int
+ged_selection_clear(struct ged *gedp, const char *set_name);
+
+GED_EXPORT extern int
+ged_selection_clear_matching(struct ged *gedp, const char *set_pattern);
+
+GED_EXPORT extern int
+ged_selection_select_path(struct ged *gedp,
+			  const char *set_name,
+			  const char *path,
+			  int recompute_hierarchy);
+
+GED_EXPORT extern int
+ged_selection_select_path_matching(struct ged *gedp,
+				   const char *set_pattern,
+				   const char *path,
+				   int recompute_hierarchy);
+
+GED_EXPORT extern int
+ged_selection_deselect_path(struct ged *gedp,
+			    const char *set_name,
+			    const char *path,
+			    int recompute_hierarchy);
+
+GED_EXPORT extern int
+ged_selection_deselect_path_matching(struct ged *gedp,
+				     const char *set_pattern,
+				     const char *path,
+				     int recompute_hierarchy);
+
+GED_EXPORT extern int
+ged_selection_select_path_ids(struct ged *gedp,
+			      const char *set_name,
+			      const ged_db_index_id *path,
+			      size_t path_len,
+			      int recompute_hierarchy);
+
+GED_EXPORT extern int
+ged_selection_deselect_path_ids(struct ged *gedp,
+				const char *set_name,
+				const ged_db_index_id *path,
+				size_t path_len,
+				int recompute_hierarchy);
+
+GED_EXPORT extern int
+ged_selection_recompute(struct ged *gedp, const char *set_name);
+
+GED_EXPORT extern int
+ged_selection_recompute_matching(struct ged *gedp, const char *set_pattern);
+
+GED_EXPORT extern int
+ged_selection_expand_matching(struct ged *gedp, const char *set_pattern);
+
+GED_EXPORT extern int
+ged_selection_collapse_matching(struct ged *gedp, const char *set_pattern);
+
+/**
+ * Synchronize semantic selection state into retained draw/view selection
+ * records.  Returns non-zero when draw/view selection state changed.
+ */
+GED_EXPORT extern int
+ged_selection_draw_sync(struct ged *gedp, const char *set_name);
+
+GED_EXPORT extern int
+ged_selection_draw_sync_matching(struct ged *gedp, const char *set_pattern);
+
+GED_EXPORT extern int
+ged_selection_is_path_selected(struct ged *gedp,
+			       const char *set_name,
+			       ged_db_index_id path_hash);
+
+GED_EXPORT extern int
+ged_selection_is_path_active(struct ged *gedp,
+			     const char *set_name,
+			     ged_db_index_id path_hash);
+
+GED_EXPORT extern int
+ged_selection_is_path_active_parent(struct ged *gedp,
+				    const char *set_name,
+				    ged_db_index_id path_hash);
+
+GED_EXPORT extern int
+ged_selection_is_object_parent(struct ged *gedp,
+			       const char *set_name,
+			       ged_db_index_id object_id);
+
+GED_EXPORT extern int
+ged_selection_is_object_immediate_parent(struct ged *gedp,
+					 const char *set_name,
+					 ged_db_index_id object_id);
+
+GED_EXPORT extern int
+ged_selection_is_object_grand_parent(struct ged *gedp,
+				     const char *set_name,
+				     ged_db_index_id object_id);
+
+__END_DECLS
+
+#endif /* GED_SELECTION_STATE_H */
+
+/** @} */
+
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/ged/view.h

@@ -34,13 +34,14 @@
 #include "rt/db_fullpath.h"
 #include "rt/db_instance.h"
 #include "ged/defines.h"
+#include "ged/bsg_ged_draw.h"
 
 __BEGIN_DECLS
 
 
 /** Check if a drawable exists */
 #define GED_CHECK_DRAWABLE(_gedp, _flags) \
-    if (!ged_dl(_gedp)) { \
+    if (!ged_draw_scene_available(_gedp)) { \
 	int ged_check_drawable_quiet = (_flags) & GED_QUIET; \
 	if (!ged_check_drawable_quiet) { \
 	    bu_vls_trunc((_gedp)->ged_result_str, 0); \
@@ -60,22 +61,7 @@ __BEGIN_DECLS
 	return (_flags); \
     }
 
-struct ged_bv_data {
-    struct db_full_path s_fullpath;
-    void *u_data;
-};
-
-/* defined in display_list.c */
-GED_EXPORT void dl_set_iflag(struct bu_list *hdlp, int iflag);
-GED_EXPORT extern void dl_color_soltab(struct bu_list *hdlp, struct db_i *dbip);
-GED_EXPORT extern void dl_erasePathFromDisplay(struct ged *gedp, const char *path, int allow_split);
-GED_EXPORT extern struct display_list *dl_addToDisplay(struct bu_list *hdlp, struct db_i *dbip, const char *name);
-
-/* Check ged_bv data associated with a display list */
-GED_EXPORT extern unsigned long long ged_dl_hash(struct display_list *dl);
-
-
-GED_EXPORT extern int ged_export_polygon(struct ged *gedp, bv_data_polygon_state *gdpsp, size_t polygon_i, const char *sname);
+GED_EXPORT extern int ged_export_polygon(struct ged *gedp, bsg_data_polygon_state *gdpsp, size_t polygon_i, const char *sname);
 GED_EXPORT extern struct bg_polygon *ged_import_polygon(struct ged *gedp, const char *sname);
 GED_EXPORT extern int ged_polygons_overlap(struct ged *gedp, struct bg_polygon *polyA, struct bg_polygon *polyB);
 GED_EXPORT extern void ged_polygon_fill_segments(struct ged *gedp, struct bg_polygon *poly, vect2d_t vfilldir, fastf_t vfilldelta);
@@ -205,19 +191,6 @@ GED_EXPORT extern int ged_tra_args(struct ged *gedp, int argc, const char *argv[
  * case, that may simplify some things.
  */
  
-// TODO - once this settles down, give it a magic number so we can type
-// check it after a void cast
-struct draw_update_data_t {
-    struct db_i *dbip;
-    struct db_full_path *fp;
-    const struct bn_tol *tol;
-    const struct bg_tess_tol *ttol;
-    struct bv_mesh_lod_context *mesh_c;
-};
-
-GED_EXPORT extern unsigned long long dl_name_hash(struct ged *gedp);
-
-
 /**
  * Return ged selections for specified object. Created if it doesn't
  * exist.
@@ -235,14 +208,8 @@ GED_EXPORT struct rt_selection_set *ged_get_selection_set(struct ged *gedp,
 
 
 
-/* Accessors for display list based drawing info.  Eventually we want to migrate
- * off of direct usage of these containers completely, but for now the older
- * drawing path (which MGED and Archer use) needs them.
- */
 typedef void (*ged_drawable_notify_func_t)(int);
 
-GED_EXPORT struct display_list *
-ged_dl(struct ged *gedp);
 GED_EXPORT void
 ged_dl_notify_func_set(struct ged *gedp, ged_drawable_notify_func_t f);
 GED_EXPORT ged_drawable_notify_func_t
@@ -256,7 +223,7 @@ ged_dl_notify_func_get(struct ged *gedp);
  * This will almost certainly move elsewhere - its presence here should be
  * considered temporary and not relied on from an API design perspective.
  */
-GED_EXPORT extern void nmg_plot_eu(struct ged *gedp, struct edgeuse *es_eu, const struct bn_tol *tol, struct bu_list *vlfree);
+GED_EXPORT extern void nmg_plot_eu(struct ged *gedp, struct edgeuse *es_eu, const struct bn_tol *tol);
 
 
 __END_DECLS

include/nmg.h

@@ -92,7 +92,6 @@
 #include "bu/ptbl.h"
 #include "bg/plane.h"
 #include "bn/tol.h"
-#include "bv/vlist.h"
 #include "vmath.h"
 
 __BEGIN_DECLS
@@ -105,6 +104,7 @@ __BEGIN_DECLS
 #include "nmg/topology.h"
 
 #include "nmg/debug.h"
+#include "nmg/display.h"
 #include "nmg/globals.h"
 #include "nmg/vertex.h"
 #include "nmg/edge.h"
@@ -115,7 +115,6 @@ __BEGIN_DECLS
 #include "nmg/model.h"
 #include "nmg/nurb.h"
 #include "nmg/ray.h"
-#include "nmg/plot.h"
 #include "nmg/print.h"
 #include "nmg/index.h"
 #include "nmg/radial.h"

include/nmg/CMakeLists.txt

@@ -3,6 +3,7 @@ set(
   check.h
   debug.h
   defines.h
+  display.h
   edge.h
   face.h
   globals.h

include/nmg/display.h

@@ -0,0 +1,68 @@
+/*                      D I S P L A Y . H
+ * BRL-CAD
+ *
+ * Copyright (c) 2026 United States Government as represented by
+ * the U.S. Army Research Laboratory.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this file; see the file named COPYING for more
+ * information.
+ */
+/** @addtogroup nmg_display
+ */
+/** @{ */
+/** @file nmg/display.h */
+
+#ifndef NMG_DISPLAY_H
+#define NMG_DISPLAY_H
+
+#include "common.h"
+#include "nmg/defines.h"
+
+__BEGIN_DECLS
+
+struct bn_tol;
+struct bsg_line_layer_builder;
+struct edgeuse;
+struct model;
+struct nmgregion;
+struct shell;
+
+/* typed display geometry */
+NMG_EXPORT extern void nmg_line_layer_around_eu(struct bsg_line_layer_builder *plot,
+						const struct edgeuse *arg_eu,
+						long *tab,
+						int fancy,
+						const struct bn_tol *tol);
+NMG_EXPORT extern void nmg_line_layer_s(struct bsg_line_layer_builder *plot,
+					const struct shell *s,
+					int fancy);
+NMG_EXPORT extern void nmg_line_layer_r(struct bsg_line_layer_builder *plot,
+					const struct nmgregion *r,
+					int fancy);
+NMG_EXPORT extern void nmg_line_layer_m(struct bsg_line_layer_builder *plot,
+					const struct model *m,
+					int fancy);
+
+__END_DECLS
+
+#endif  /* NMG_DISPLAY_H */
+/** @} */
+/*
+ * Local Variables:
+ * mode: C
+ * tab-width: 8
+ * indent-tabs-mode: t
+ * c-file-style: "stroustrup"
+ * End:
+ * ex: shiftwidth=4 tabstop=8
+ */

include/nmg/globals.h

@@ -41,12 +41,6 @@ __BEGIN_DECLS
  */
 NMG_EXPORT extern uint32_t nmg_debug;
 
-/**
- * @brief
- * global nmg animation vblock callback
- */
-NMG_EXPORT extern void (*nmg_vlblock_anim_upcall)(void);
-
 /**
  * @brief
  * global nmg mged display debug callback (ew)

include/nmg/plot.h

@@ -120,71 +120,8 @@ NMG_EXPORT extern void nmg_pl_r(FILE *fp,
 NMG_EXPORT extern void nmg_pl_m(FILE *fp,
 				const struct model *m,
 				struct bu_list *vlfree);
-NMG_EXPORT extern void nmg_vlblock_v(struct bv_vlblock *vbp,
-				     const struct vertex *v,
-				     long *tab,
-				     struct bu_list *vlfree);
-NMG_EXPORT extern void nmg_vlblock_e(struct bv_vlblock *vbp,
-				     const struct edge *e,
-				     long *tab,
-				     int red,
-				     int green,
-				     int blue,
-				     struct bu_list *vlfree);
-NMG_EXPORT extern void nmg_vlblock_eu(struct bv_vlblock *vbp,
-				      const struct edgeuse *eu,
-				      long *tab,
-				      int red,
-				      int green,
-				      int blue,
-				      int fancy,
-				      struct bu_list *vlfree);
-NMG_EXPORT extern void nmg_vlblock_euleft(struct bu_list                 *vh,
-					  const struct edgeuse           *eu,
-					  const point_t                  center,
-					  const mat_t                    mat,
-					  const vect_t                   xvec,
-					  const vect_t                   yvec,
-					  double                         len,
-					  struct bu_list 	        *vlfree,
-					  const struct bn_tol            *tol);
-NMG_EXPORT extern void nmg_vlblock_around_eu(struct bv_vlblock           *vbp,
-					     const struct edgeuse        *arg_eu,
-					     long                        *tab,
-					     int                 fancy,
-					     struct bu_list *vlfree,
-					     const struct bn_tol *tol);
-NMG_EXPORT extern void nmg_vlblock_lu(struct bv_vlblock *vbp,
-				      const struct loopuse *lu,
-				      long *tab,
-				      int red,
-				      int green,
-				      int blue,
-				      int fancy,
-				      struct bu_list *vlfree);
-NMG_EXPORT extern void nmg_vlblock_fu(struct bv_vlblock *vbp,
-				      const struct faceuse *fu,
-				      long *tab, int fancy, struct bu_list *vlfree);
-NMG_EXPORT extern void nmg_vlblock_s(struct bv_vlblock *vbp,
-				     const struct shell *s,
-				     int fancy,
-				     struct bu_list *vlfree);
-NMG_EXPORT extern void nmg_vlblock_r(struct bv_vlblock *vbp,
-				     const struct nmgregion *r,
-				     int fancy,
-				     struct bu_list *vlfree);
-NMG_EXPORT extern void nmg_vlblock_m(struct bv_vlblock *vbp,
-				     const struct model *m,
-				     int fancy,
-				     struct bu_list *vlfree);
 
 /* visualization helper routines */
-NMG_EXPORT extern void nmg_pl_edges_in_2_shells(struct bv_vlblock        *vbp,
-						long                     *b,
-						const struct edgeuse     *eu,
-						int                      fancy,
-						struct bu_list *vlfree,
-						const struct bn_tol      *tol);
 NMG_EXPORT extern void nmg_pl_isect(const char           *filename,
 				    const struct shell   *s,
 				    struct bu_list *vlfree,