Represents a geometric primitive with vertex attributes, materials, and rendering data. A primitive is the basic building block for rendering 3D geometry.

Hierarchy (view full)

Constructors

Properties

_prevMaterial: WeakRef<Material>
_sortkey: number = 0
_tags: RnTags = {}

Collection of tags associated with this object

_viewDepth: number = 0
InvalidObjectUID: -1 = -1

Invalid object UID constant

currentMaxObjectCount: number = 0

Current maximum object count for UID generation

Accessors

  • get AABB(): AABB
  • Gets the axis-aligned bounding box for this primitive. The AABB is calculated from position data and cached until positions change.

    Returns AABB

    The bounding box containing all vertices

  • get objectUID(): number
  • Gets the unique object identifier

    Returns number

    The object's UID

  • get positionAccessorVersion(): number
  • Gets the version number of the position accessor. Used to track when position data has been updated.

    Returns number

    The current position accessor version

  • get uniqueName(): string
  • Gets the unique name of this object

    Returns string

    The unique name string

  • get variantUpdateCount(): number
  • Gets the current count of material variant updates across all primitives. This counter is incremented whenever material variants are modified.

    Returns number

    The number of material variant updates since application start

Methods

  • Internal

    Creates a backup of the current material for later restoration. Used internally for material switching operations.

    Returns void

  • Internal

    Associates this primitive with a parent mesh. This establishes the hierarchical relationship between mesh and primitive.

    Parameters

    • mesh: Mesh

      The mesh that this primitive belongs to

    Returns void

  • Gets the cached fingerprint string of the primitive.

    Returns string

    The fingerprint string used for primitive identification

  • Internal

    Restores the previously backed-up material if it still exists. Used internally for reverting material changes.

    Returns void

  • Applies a previously registered material variant by its name. Changes the current material to the variant if it exists.

    Parameters

    • variantName: string

      The name of the variant to apply

    Returns void

  • Calculates a unique fingerprint string for the primitive based on its properties. The fingerprint includes mode, indices, targets, and attributes configuration. This is used for efficient primitive comparison and caching.

    Returns void

  • Performs ray casting against this primitive's geometry. Tests intersection between a ray and the triangles of this primitive.

    Parameters

    • origVec3: IVector3

      The origin point of the ray

    • dirVec3: IVector3

      The direction vector of the ray (should be normalized)

    • isFrontFacePickable: boolean

      Whether front-facing triangles can be hit

    • isBackFacePickable: boolean

      Whether back-facing triangles can be hit

    • dotThreshold: number

      Threshold for determining front/back face orientation

    • hasFaceNormal: boolean

      Whether to use face normals for culling

    Returns RaycastResultEx1

    Ray casting result with intersection data or failure indication

  • Converts this indexed primitive to non-indexed geometry. Expands vertex data by duplicating vertices according to indices. This can increase memory usage but simplifies some rendering operations.

    Returns void

  • Copies vertex data from a descriptor into this primitive. Creates appropriate buffers and accessors for the provided data.

    Parameters

    Returns void

  • Creates GPU vertex and index buffers for this primitive. This prepares the primitive for rendering by uploading data to the GPU.

    Returns boolean

    True if buffers were created, false if they already exist

  • Deletes the GPU vertex and index buffers for this primitive. Frees GPU memory when the primitive is no longer needed.

    Returns boolean

    True if buffers were deleted, false if no buffers exist

  • Gets the name of the currently applied material variant.

    Returns string

    The name of the active variant, or an empty string if no variant is active

  • Determines the bit size required for indices based on the index accessor type.

    Returns "uint16" | "uint32"

    'uint16' for unsigned short/byte indices, 'uint32' for unsigned int indices

    Error if no index accessor exists or the component type is unsupported

  • Retrieves a complete tag object (name and value) for the specified tag name

    Parameters

    • tagName: string

      The name of the tag to retrieve

    Returns Tag

    A Tag object containing the name and value

  • Retrieves the value associated with a specific tag name

    Parameters

    • tagName: string

      The name of the tag whose value to retrieve

    Returns any

    The tag value, or undefined if the tag doesn't exist

  • Calculates the triangle count for indexed primitives. The count depends on the primitive mode (triangles, triangle strip, etc.).

    Returns number

    The number of triangles that will be rendered with indices

  • Calculates the triangle count for non-indexed primitives. The count depends on the primitive mode and vertex count.

    Returns number

    The number of triangles that will be rendered from vertices

  • Gets the material associated with a specific variant name.

    Parameters

    • variantName: string

      The name of the variant to look up

    Returns undefined | Material

    The material for the variant, or undefined if the variant doesn't exist

  • Gets all registered variant names for this primitive.

    Returns string[]

    An array containing all variant names

  • Gets the vertex count for indexed primitives. For indexed rendering, this returns the number of indices.

    Returns number

    The number of indices if indexed, otherwise the vertex count

  • Gets the vertex count based on vertex buffer data.

    Returns number

    The number of vertices in the vertex buffers

  • Checks if this primitive uses index-based rendering.

    Returns boolean

    True if the primitive has an index buffer, false otherwise

  • Checks whether this object has a tag with the specified name

    Parameters

    • tagName: string

      The name of the tag to check for

    Returns boolean

    True if the tag exists (value is not null/undefined), false otherwise

  • Checks if this primitive uses blending (transparency) for rendering.

    Returns boolean

    True if the material has blending enabled, false otherwise

  • Checks if this primitive is opaque (not transparent).

    Returns boolean

    True if the primitive is opaque, false if it uses blending

  • Checks if this object has a tag with the specified name and value

    Parameters

    • tagName: string

      The tag name to match

    • tagValue: string

      The tag value to match

    Returns boolean

    True if the object has a matching tag, false otherwise

  • Checks if this object has all the specified tags with exactly matching values

    Parameters

    • tags: RnTags

      Object containing tag names as keys and expected values

    Returns boolean

    True if all specified tags exist with matching values, false otherwise

  • Checks if the object's combined tag string contains all the provided search strings. This allows for flexible searching within tag names and values.

    Parameters

    • stringArray: string[]

      Array of strings that must all be present in the combined tag string

    Returns boolean

    True if all strings are found in the combined tag string, false otherwise

  • Notifies the primitive that its position accessor has been updated. This triggers recalculation of bounding boxes and mesh updates.

    Parameters

    • accessorVersion: number

      The new version number of the updated accessor

    Returns void

  • Sets blend shape (morph) targets for this primitive. Blend shapes allow vertex animation by interpolating between target positions.

    Parameters

    • targets: Attributes[]

      Array of attribute maps representing morph targets

    Returns void

  • Sets the vertex and index data for this primitive. This is the main method for configuring primitive geometry and rendering properties.

    Parameters

    • attributes: Attributes

      Map of vertex attributes with their semantic meanings

    • mode: PrimitiveModeEnum

      The primitive rendering mode (triangles, triangle strip, etc.)

    • Optionalmaterial: Material

      Optional material to assign (uses default if not provided)

    • OptionalindicesAccessor: Accessor

      Optional index accessor for indexed rendering

    Returns void

  • Registers a material variant for this primitive with a specific name. Material variants allow switching between different materials at runtime.

    Parameters

    • variantName: string

      The unique name for this material variant

    • material: Material

      The material to associate with the variant name

    Returns void

  • Updates the sort key by setting a specific bit range with a value. Sort keys are used to optimize rendering order for transparency and material batching.

    Parameters

    • offset: number

      The bit offset position where to start writing

    • length: PrimitiveSortKeyLength

      The number of bits to write

    • value: number

      The value to encode in the specified bit range

    Returns void

  • Attempts to set a tag on this object. If the tag already exists, it will be replaced.

    Parameters

    • tag: Tag

      The tag object containing the name and value to set

    Returns boolean

    True if the tag was successfully set, false if the tag name contains invalid characters

  • Attempts to set a unique name for this object

    Parameters

    • name: string

      The desired unique name

    • toAddNameIfConflict: boolean

      If true, appends UID to make name unique when conflicts occur; if false, fails on conflict

    Returns boolean

    True if the name was successfully set, false if there was a conflict and toAddNameIfConflict was false

  • Updates the GPU vertex and index buffers with current data. Used when vertex data has been modified and needs to be re-uploaded.

    Returns boolean

    True if buffers were updated, false if no buffers exist

  • Validates that a tag string contains only allowed characters (alphanumeric and underscore)

    Parameters

    • val: string

      The string to validate

    Returns boolean

    True if the string contains only valid characters, false if it contains invalid characters

  • Creates a new primitive from a descriptor containing vertex data. This is a factory method that creates and initializes a primitive in one step.

    Parameters

    Returns Primitive

    A new primitive instance with the specified data

  • Retrieves a primitive instance by its unique identifier.

    Parameters

    • primitiveUid: number

      The unique identifier of the primitive to find

    Returns undefined | Primitive

    The primitive if found and still exists, otherwise undefined

  • Gets the total number of primitives created in the application.

    Returns number

    The total count of primitives

  • Gets a primitive with morph targets by its index.

    Parameters

    • primitiveIdx: number

      The index of the primitive in the morph targets collection

    Returns undefined | Primitive

    The primitive if found and still exists, otherwise undefined

  • Gets the index of a primitive with morph targets by its UID.

    Parameters

    • primitiveUid: number

      The unique identifier of the primitive

    Returns undefined | number

    The index if the primitive has morph targets, otherwise undefined

  • Retrieves an RnObject instance by its unique identifier

    Parameters

    • objectUid: number

      The unique identifier of the object to retrieve

    Returns undefined | RnObject

    The RnObject instance or undefined if not found or garbage collected

  • Searches for the first object that has a specific tag with the given value

    Parameters

    • tag: string

      The tag name to search for

    • value: string

      The tag value to match

    Returns undefined | WeakRef<RnObject>

    WeakRef to the first matching object, or undefined if not found