The high-level API module provides an interface to the scene database on a higher level than the standard low-level SCENE interface. It is patterned after the .mi language; most .mi constructs have direct high-level API call interface equivalents. The following table contrasts the SCENE and high-level API (abbreviated API in this document) interfaces:
| SCENE | API |
|---|---|
| based on struct manipulation | based on .mi2 entities |
| optimized for rendering | optimized for scene definition |
| static element sizes | dynamic element sizes |
| avoids reallocation and copying | reallocation and copying |
| internal links by tag | internal links by name |
| higher porting effort | low porting effort |
| no output shader support | full output shader support |
Based on struct manipulation means that the SCENE module provides allocation functions for the various database element types. All operations are done in terms of these data structures. If an element such as a geometric object consists of multiple data structures, the caller must separately allocate and combine them. In contrast, API operates on .mi element level, which means that entities such as geometric objects are defined as a unit, and that the implementation details are handled automatically.
Optimized for rendering means that SCENE data structures are designed for optimum rendering efficiency, not for simplicity or ease of access. API follows scene structuring elements and is very easy to use. API does introduce some minor overhead during scene construction but not during rendering.
Static element sizes means that variable-sized database elements such as vertex lists must be preallocated with the correct size. The number of components must be known in advance. Reallocation is possible but expensive in terms of speed and memory fragmentation. The API module buffers the components of variable-sized entities in linked page lists and allocates the database entry when the definition of an element is complete.
Avoiding reallocation and copying is a consequence of the previous point. SCENE requires preallocation of data structures, so that after preallocation the data can be written directly into database memory. API buffers data, which implies temporary data structures for some entities and a copy operation from the buffers to database memory. This can make API slightly slower than SCENE for very large geometric objects.
Internal links by tag means that SCENE will return a 32-bit identifier called a tag whenever a database element is allocated. To link two database elements, such as attaching a vertex list to a geometric object, the tag is either written into the parent element, or a special link call is used (depending on what type of link is formed). API does not use tags for scene elements; all entities have a name and links are established by name. However, API uses tags for functions (shaders) because functions are normally unnamed.
Higher porting effort results from the fact that whenever internal data structures are changed there is a higher probability that code using these data structures must be changed also. API calls are highly stable, and new features are provided in an upward-compatible way by providing new access functions that require no change to code that uses the existing functions.
Copyright © 1986, 2015 NVIDIA ARC GmbH. All rights reserved.