Region-ID-based material/color table management for BRL-CAD databases. More...

#include "common.h"
#include "rt/defines.h"
#include "bu/vls.h"

Include dependency graph for mater.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	mater_info

struct	mater

Macros
#define	RT_MATER_INFO_INIT_ZERO { VINIT_ZERO, 0.0, 0, 0, 0, NULL }

#define	RT_MATER_INFO_INIT_IDN { {1.0, 0.0, 0.0} , -1.0, 0, 0, 0, NULL }

#define	MATER_NULL ((struct mater *)0)

#define	MATER_NO_ADDR ((b_off_t)0)
	sentinel: entry has no backing database record

Functions
void	db_mater_color_region (struct db_i dbip, struct region regp)

void	db_mater_add (struct db_i *dbip, int low, int hi, int r, int g, int b, b_off_t addr)

void	db_mater_insert (struct db_i dbip, struct mater newp)

void	db_mater_to_vls (struct bu_vls str, struct db_i dbip)

struct mater *	db_mater_head (struct db_i *dbip)

void	db_mater_set_head (struct db_i dbip, struct mater newmat)

struct mater *	db_mater_dup (struct db_i *dbip)

void	db_mater_free (struct db_i *dbip)

Deprecated global material API (use db_mater_* instead)
The following functions operated on a single process-wide (global) material table and are retained for backward compatibility only. New code must use the per-database `db_mater_`() functions above. Deprecated:* since 7.42 - use db_mater_head(), db_mater_set_head(), db_mater_dup(), db_mater_free(), db_mater_insert(), db_mater_add(), db_mater_to_vls(), and db_mater_color_region() instead.
DEPRECATED struct mater *	rt_material_head (void)

DEPRECATED void	rt_new_material_head (struct mater *newmat)

DEPRECATED struct mater *	rt_dup_material_head (void)

DEPRECATED void	rt_color_free (void)

DEPRECATED void	rt_insert_color (struct mater *newp)

DEPRECATED void	rt_color_addrec (int low, int hi, int r, int g, int b, b_off_t addr)

DEPRECATED void	rt_vls_color_map (struct bu_vls *str)

DEPRECATED void	rt_region_color_map (struct region *regp)

Detailed Description

Region-ID-based material/color table management for BRL-CAD databases.

BRL-CAD supports a region-ID color table: a sorted, non-overlapping list of struct mater entries that map integer region-ID ranges to RGB colors. This table is stored per-database (in db_i) and is used by the ray tracer and display logic to assign colors to regions based on their region ID when no explicit color attribute is present on the object itself.

The table is populated when the database is opened (from _GLOBAL attributes for v5 databases, or from ID_COLORTAB records for v4 databases) and is freed when the database is closed.

Typical usage pattern:

At database load time, db_mater_add() is called for each stored color record, which calls db_mater_insert() to build the sorted in-memory list.
At ray-trace / display time, db_mater_color_region() walks the table to apply an override color to a region whose ID falls within a mapped range.
To inspect or serialize the current table, use db_mater_head() to obtain the list head and iterate via mt_forw, or call db_mater_to_vls() for a string representation suitable for storing in a _GLOBAL attribute.
db_mater_free() releases all in-memory table entries (called by db_close()).

Definition in file mater.h.

Macro Definition Documentation

◆ RT_MATER_INFO_INIT_ZERO

#define RT_MATER_INFO_INIT_ZERO { VINIT_ZERO, 0.0, 0, 0, 0, NULL }

Definition at line 73 of file mater.h.

◆ RT_MATER_INFO_INIT_IDN

#define RT_MATER_INFO_INIT_IDN { {1.0, 0.0, 0.0} , -1.0, 0, 0, 0, NULL }

Definition at line 75 of file mater.h.

◆ MATER_NULL

#define MATER_NULL ((struct mater *)0)

Definition at line 93 of file mater.h.

◆ MATER_NO_ADDR

#define MATER_NO_ADDR ((b_off_t)0)

sentinel: entry has no backing database record

Definition at line 94 of file mater.h.

Function Documentation

◆ db_mater_color_region()

void db_mater_color_region	(	struct db_i *	dbip,
		struct region *	regp
	)

extern

Apply the region-ID color table to a region.

If regp->reg_regionid falls within a mapped range in the table associated with dbip, the region's reg_mater.ma_color and ma_color_valid fields are updated accordingly. Has no effect if the region ID does not match any entry.

Parameters

dbip	database whose material table is consulted
regp	region to color

◆ db_mater_add()

void db_mater_add	(	struct db_i *	dbip,
		int	low,
		int	hi,
		int	r,
		int	g,
		int	b,
		b_off_t	addr
	)

extern

Construct a struct mater entry from raw record data and insert it into the database's material table.

This is the primary loader function called from database scan routines (e.g., db_scan() for v4, db5_import_color_table() for v5) to populate the in-memory table from stored records.

Parameters

dbip	database whose material table receives the new entry
low	lower bound of the region ID range
hi	upper bound of the region ID range
r	red component (0-255)
g	green component (0-255)
b	blue component (0-255)
addr	backing database address (`MATER_NO_ADDR` if none)

◆ db_mater_insert()

void db_mater_insert	(	struct db_i *	dbip,
		struct mater *	newp
	)

extern

Insert a struct mater entry into a database's material table, maintaining sorted order and resolving any overlaps with existing entries.

Ownership of newp is transferred to the table; do not free it after calling this function.

Parameters

dbip	database whose material table is modified
newp	entry to insert (must be heap-allocated)

◆ db_mater_to_vls()

void db_mater_to_vls	(	struct bu_vls *	str,
		struct db_i *	dbip
	)

extern

Serialize the database's material table to a bu_vls string.

Each entry is written as "{low high r g b} " and appended to str. The resulting string is suitable for storage in the regionid_colortable attribute of a v5 _GLOBAL object.

Parameters

str	output string (appended to; caller must initialize)
dbip	database whose material table is serialized

◆ db_mater_head()

struct mater * db_mater_head ( struct db_i * dbip )

extern

Return the head of the material table list for a database.

The returned pointer is the first entry of the sorted list; iterate using mt_forw to traverse all entries. Returns MATER_NULL if the table is empty.

Parameters

dbip	database to query

Returns: pointer to first struct mater entry, or MATER_NULL

◆ db_mater_set_head()

void db_mater_set_head	(	struct db_i *	dbip,
		struct mater *	newmat
	)

extern

Replace the material table list head for a database.

This is a low-level setter. It does not free the old list; call db_mater_free() first if the old entries should be released. Typically used when swapping in a pre-built list (e.g., after db_mater_dup()).

Parameters

dbip	database to update
newmat	new list head (may be `MATER_NULL` to clear the table)

◆ db_mater_dup()

struct mater * db_mater_dup ( struct db_i * dbip )

extern

Return a deep copy of the material table for a database.

All entries are duplicated; the caller owns the returned list and is responsible for freeing it (e.g., by iterating and calling bu_free(), or by inserting into another database's table via db_mater_set_head() and letting db_mater_free() handle cleanup at close time).

Parameters

dbip	database whose material table is duplicated

Returns: head of the new list, or MATER_NULL if the table is empty

◆ db_mater_free()

void db_mater_free ( struct db_i * dbip )

extern

Free all entries in the material table of a database.

After this call the table is empty (db_mater_head() returns MATER_NULL). Called automatically by db_close().

Parameters

dbip	database whose material table is freed

◆ rt_material_head()

DEPRECATED struct mater * rt_material_head ( void )

extern

Deprecated:: use db_mater_head()

◆ rt_new_material_head()

DEPRECATED void rt_new_material_head ( struct mater * newmat )

extern

Deprecated:: use db_mater_set_head()

◆ rt_dup_material_head()

DEPRECATED struct mater * rt_dup_material_head ( void )

extern

Deprecated:: use db_mater_dup()

◆ rt_color_free()

DEPRECATED void rt_color_free ( void )

extern

Deprecated:: use db_mater_free()

◆ rt_insert_color()

DEPRECATED void rt_insert_color ( struct mater * newp )

extern

Deprecated:: use db_mater_insert()

◆ rt_color_addrec()

DEPRECATED void rt_color_addrec	(	int	low,
		int	hi,
		int	r,
		int	g,
		int	b,
		b_off_t	addr
	)

extern

Deprecated:: use db_mater_add()

◆ rt_vls_color_map()

DEPRECATED void rt_vls_color_map ( struct bu_vls * str )

extern

Deprecated:: use db_mater_to_vls()

◆ rt_region_color_map()

DEPRECATED void rt_region_color_map ( struct region * regp )

extern

Deprecated:: use db_mater_color_region()

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ RT_MATER_INFO_INIT_ZERO

◆ RT_MATER_INFO_INIT_IDN

◆ MATER_NULL

◆ MATER_NO_ADDR

Function Documentation

◆ db_mater_color_region()

◆ db_mater_add()

◆ db_mater_insert()

◆ db_mater_to_vls()

◆ db_mater_head()

◆ db_mater_set_head()

◆ db_mater_dup()

◆ db_mater_free()

◆ rt_material_head()

◆ rt_new_material_head()

◆ rt_dup_material_head()

◆ rt_color_free()

◆ rt_insert_color()

◆ rt_color_addrec()

◆ rt_vls_color_map()

◆ rt_region_color_map()