Db_default

Deterministic default object selection for geometry databases. More...

Files
file	default.h

Macros
#define	DB_DEFAULT_OBJECT_ATTR   "default_object"

Functions
int	db_default_object (struct db_i *dbip, struct directory **dp, struct bu_vls *msg)

Detailed Description

Deterministic default object selection for geometry databases.

Macro Definition Documentation

DB_DEFAULT_OBJECT_ATTR

#define DB_DEFAULT_OBJECT_ATTR   "default_object"

Default object attribute name stored on the v5 _GLOBAL object.

Definition at line 43 of file default.h.

Function Documentation

db_default_object()

int db_default_object ( struct db_i *  dbip, struct directory **  dp, struct bu_vls *  msg  )

extern

Select a deterministic default geometry object for commands that can operate on one database object but were not given an explicit object name.

The selection is intentionally conservative: a successful return means librt found exactly one geometry object according to the default-object rules. If the database disables default-object selection, if a rule has ambiguous matches, or if no rule matches, no object is selected and a printable explanation is written to msg when supplied.

Selection order:

1. If the v5 _GLOBAL object has DB_DEFAULT_OBJECT_ATTR set to a non-empty, non-negative value, use that value as an exact object name. Empty/false/negative values disable automatic default-object selection.
2. If there is exactly one non-hidden top-level geometry object, select it.
3. If there is exactly one non-hidden combination in the database, select it.
4. If there is exactly one non-hidden combination whose name without its final extension matches the database filename without its final extension, select it.
5. If there is exactly one top-level non-hidden combination whose name case-insensitively matches all* or scene*, select it.

Parameters

[in]	dbip	Open database instance to inspect. The routine updates database reference counts with db_update_nref() before testing top-level status.
[out]	dp	Optional output pointer. On successful selection, *dp is set to the selected directory pointer. On no selection or error, *dp is set to RT_DIR_NULL when dp is non-NULL.
[in,out]	msg	Optional caller-owned, initialized bu_vls. On return 0 or -1, explanatory text is appended, including the available top-level objects when known. On successful selection, the routine leaves msg unchanged.

Returns

1 when a unique default object was selected.

0 when no object was selected because selection is disabled, ambiguous, or no deterministic match exists.

-1 on internal failure.