Instance

Instances refer to models so that multiple instances can use the same model, changes to the models will be seen on connected instances and instances can easily refer to another model using Instance_ReplaceModel.

int Instance_Create(int Model);

Creating and deleting instances is quite fast in this engine because instances only have fixed size memory allocations that the engine can reuse. Replacing an instance's model is still much faster than deleting it and creating a new instance with another model because the other properties do not have to be changed.

Model is a valid model.

Returns the ID to a new instance using Model.

Creates a new instance with the following default values.

visible = true

mirrored = false

position = (0,0,0)

X axis = (1,0,0)

Y axis = (0,1,0)

Z axis = (0,0,1)

userdefined vectors 0..15 = (0,0,0,0)

color = (1,1,1,1)

void Instance_Delete(int Instance);

Instance is a valid instance.

Removes Instance.

void Instance_SetUserDefinedData(int Instance, int Index, float X, float Y, float Z, float W);

The 16 userdefined vectors are stored in each instance and can be used in material shaders as the Arg[0..15] float4 array.

Since they have their own buffer, calling this method will make the instance a bit slower to render because the engine have to update the buffer.

Instance is a valid instance and 0 ≤ Index ≤ 15.

The userdefined vector at Index in Instance is set to (X,Y,Z,W).

void Instance_GetUserDefinedData_OutV4(int Instance, int Index);

Instance is a valid instance and 0 ≤ Index ≤ 15.

The userdefined vector at Index in Instance is written to (X1,Y1,Z1,W1).

void Instance_SetColor(int Instance, float Red, float Green, float Blue, float Alpha);

The color vector is stored in each instance and can be used in material shaders as InstanceColor. The instance color works as the user defined array but with a name instead of index and (1,1,1,1) as default value in case that you don't want to choose a color.

Instance is a valid instance.

The color is set to (Red,Green,Blue,Alpha).

void Instance_GetColor_OutV4(int Instance);

Instance is a valid instance.

The color is written to (X1,Y1,Z1,W1).

void Instance_ReplaceModel(int Instance,int Model);

This method is extremely fast and can be used for simple animation where no interpolation is needed. For example, turning a light switch on and off.

Instance is a valid instance and Model is a valid model.

Changes a pointer in the instance so that the instance is using Model as it's new model.

void Instance_AssignBoneFrame(int Instance,int BoneFrame););

This method is the real way of animating your instances with bones. It require the model to have bones with vertices assigned to them and shaders that move the vertices using the bones. If no bone frame is assigned to the instance when showing a model with bones, the model's default pose is used for rendering.

You can either have a set of static bone frames that you reassign to multiple instances or have one dynamic bone frame for each instance that is modified before rendering the scene.

Instance is a valid instance and BoneFrame is a valid bone frame or 0 for nothing.

Changes a pointer in the instance so that the instance is using BoneFrame as it's bone frame. If BoneFrame = 0 then the bone frame is unassigned from the instance so that the model's default post is used.

void Instance_SetPosition(int Instance, float X, float Y, float Z);

Instance is a valid instance.

Changes Instance's position to (X,Y,Z)

void Instance_GetPosition_OutV3(int Instance);

Instance is a valid instance.

Writes Instance's position to (X1,Y1,Z1).

void Instance_SetXAxis(int Instance, float X, float Y, float Z);

Instance is a valid instance.

Changes Instance's X axis to (X,Y,Z)

void Instance_GetXAxis_OutV3(int Instance);

Instance is a valid instance.

Writes Instance's X axis to (X1,Y1,Z1).

void Instance_SetYAxis(int Instance, float X, float Y, float Z);

Instance is a valid instance.

Changes Instance's Y axis to (X,Y,Z)

void Instance_GetYAxis_OutV3(int Instance);

Instance is a valid instance.

Writes Instance's Y axis to (X1,Y1,Z1).

void Instance_SetZAxis(int Instance, float X, float Y, float Z);

Instance is a valid instance.

Changes Instance's Z axis to (X,Y,Z)

void Instance_GetZAxis_OutV3(int Instance);

Instance is a valid instance.

Writes Instance's Z axis to (X1,Y1,Z1).

void Instance_Get4x4System_OutM4(int Instance);

This matrix can be used to convert a 3D vector from the instance's object space to world space by multiplying (X,Y,Z,0) with the 4x4 matrix and remove the W dimension.

To convert back from world space to the instance's object space, multiply (X,Y,Z,0) with the inverse of the 4x4 matrix and remove the W dimension.

Instance is a valid instance.

Writes Instance's X axis to (X1,Y1,Z1), Y axis to (X2,Y2,Z2), Z axis to (X3,Y3,Z3) and position to (X4,Y4,Z4). W1 = 0, W2 = 0, W3 = 0 and W4 = 1 so that the 4x4 matrix can be used for multiplication and other things.

void Instance_SetVisibility(int Instance, int ShaderChannel, bool Visible);

An instance that is not visible will not be drawn but is ready to be rendered at any time so that setting the visibility is extremely fast. If you make many instances invisible during a long time, deleting and creating instances will be faster. Shader channel 1 is reserved for depth based shadows and will therefor affect if the instance is can cast shadows.

Instance is a valid instance and 0 <= ShaderChannel <= 15.

Sets the visibility of Instance when rendered using ShaderChannel.

int Instance_GetVisibility(int Instance, int ShaderChannel);

Instance is a valid instance and 0 <= ShaderChannel <= 15.

Returns 1 if the instance is visible when rendered using ShaderChannel and 0 otherwise.

void Instance_SetMirrored(int Instance, bool Mirrored);

When an instance is rendered with the mirrored property set to true, backface culling is used instead of front face culling so that the instance will be drawn correctly when the determinant of the instance's axis system is negative.

Instance is a valid instance.

Sets the mirrored property of Instance.

int Instance_GetMirrored(int Instance);

Instance is a valid instance.

Returns 1 only if the instance has mirrored face rendering and 0 otherwise.

void Instance_SetTextureOverride(int Instance, int OverrideChannel, int DrawSurfaceOrTexture);

This method tells an instance that any texture in it's model listening to OverrideChannel will be replaced by DrawSurfaceOrTexture.

Model_Part_SetTextureOverride is used in the model to tell a texture slot to allow this override.

Instance is a valid instance, 0 ≤ OverrideChannel ≤ 15 and DrawSurfaceOrTexture is 0, a valid texture or a valid draw surface.

Any old input in Instance at OverrideChannel is disconnected and if DrawSurfaceOrTexture is not 0, DrawSurfaceOrTexture will be connected to Instance at OverrideChannel.

int Instance_GetTextureOverride(int Instance, int OverrideChannel);

Use Engine_GetTypeFromID to know the type of the returned handle.

Instance is a valid instance and 0 ≤ OverrideChannel ≤ 15

Returns any reference to the connected surface in Instance's at OverrideChannel. If no input is assigned to Instance at OverrideChannel, 0 is returned.

void Instance_SetDetailLevel(int Instance, int DetailLevel);

This method will set the visible detail level for an instance by showing and hiding different parts.

If the model don't have multi resolution then this does nothing to the visible result.

The integer detail level is decided by the closest integer to DetailLevel. This value can hide parts that should not be seen in that detail level.

Instance is a valid instance.

Sets the detail level of Instance to DetailLevel clamped between 0 and 2.

int Instance_GetDetailLevel(int Instance);

Instance is a valid instance.

Returns Instance's integer detail level or -1 if the precondition is broken.

void Instance_SetDetailLevel_Float(int Instance, float DetailLevel);

This method will set the DetailLevel variable for Instance so that it can be accessed in it's HLSL material shaders.

The floating point detail level is not affecting the visibility of parts.

Instance is a valid instance.

Sets the detail level of Instance to DetailLevel clamped between 0 and 2.

float Instance_GetDetailLevel_Float(int Instance);

Instance is a valid instance.

Returns Instance's floating point detail level or -1.0 if the precondition is broken.

void Instance_SetAutoDetailLevel(int Instance, bool AutoDetailLevel);

Enabling this will allow the instance's detail level to be updated automatically using the call Enviroment_UpdateAutomaticDetailLevels.

Instance is a valid instance.

Enable automatic detail level if AutoDetailLevel is true. Disable it otherwise.

int Instance_GetAutoDetailLevel(int Instance);

Instance is a valid instance.

Returns 1 if the instance is using automatic detail level. 0 is returned otherwise.

void Instance_PlaceAtRigidBody(int Instance,int RigidBody,bool UseLocalScaling);

This method will not interpolate the location so that the location in the last physical step is used.

You can use this method when you just want to place an instance on a static rigid body that will never move.

This method does not create any relation between the instance and the rigid body.

Instance is a valid instance and RigidBody is a valid rigid body.

Instance is placed at RigidBody and if UseLocalScaling is true then Instance's axis system is scaled by RigidBody's collision shape's local scaling.

void Instance_PlaceAtRigidBody_Interpolated(int Instance,int RigidBody, float TimeOffset,bool UseLocalScaling);

This method works like Instance_PlaceAtRigidBody but interpolates the rigid body's transformation by multiplying the linear and angular velocity with TimeOffset.

This method does not create any relation between the instance and the rigid body.

TimeOffset should be the amount of time that remained after making a number of calls to Physics_Step with your fixed timestep

Instance is a valid instance, RigidBody is a valid rigid body and 0 <= TimeOffset < your fixed timestep given to Physics_Step.

Instance is placed where RigidBody is expected to be after TimeOffset amount of time and if UseLocalScaling is true then Instance's axis system is scaled by RigidBody's collision shape's local scaling.

void Instance_FollowRigidBody(int Instance, int RigidBody, bool UseLocalScaling);

If you never move RigidBody because it is static then calling Instance_PlaceAtRigidBody after creating Instance will do the same thing at exactly the same performance and memory cost.

Since a visual instance do not need to follow a rigid body, you may delete the rigid body before the instances that are using it without getting a warning because the engine will remove the connections automatically.

Instance is a valid instance and RigidBody is a valid rigid body.

The engine makes sure that Instance is following RigidBody as long as you keep calling Physics_LetInstancesFollowRigidBodies or Physics_LetInstancesFollowRigidBodies_Interpolated.

int Instance_GetFollowedRigidBody(int Instance);

Instance is a valid instance.

Returns the ID of the rigid body being followed by Instance. 0 means none and -1 means broken precondition.