Model Primitive

The model primitive can load and render COLLADA and AGI's MDL models. COLLADA is an industry standard, XML-based 3D model format. MDL is the 3D model format used by STK. We recommend using COLLADA models, although they consume slightly more disk space since they are XML-based. Models can be downloaded from AGI's website.

Models can be initialized as shown below:

[C#] Copy Code
IAgStkGraphicsSceneManager manager = ((IAgScenario)root.CurrentScenario).SceneManager;
IAgStkGraphicsModelPrimitive model = manager.Initializers.ModelPrimitive.InitializeWithStringUri(modelUri);
Array position = new object[] { 39.88, -75.25, 5000 };
model.SetPositionCartographic("Earth", ref position);

The orientation of the model depends on the model itself. For example, in the hellfire.dae model, the missile is laid out lengthwise along the positive x axis. To change the orientation, use the Orientation property and provide an IAgOrientation that defines the rotation from the model's local axes to the axes of the reference frame in which the model's position is defined. In this case, the model's position is defined in the central body's fixed frame. A convenient way to compute the orientation is shown below:

[C#] Copy Code
IAgPosition origin = CreatePosition(root, 39.88, -75.25, 0);
IAgCrdnAxesFixed axes = CreateAxes(root, "Earth", origin);
IAgCrdnAxesFindInAxesResult result = root.VgtRoot.WellKnownAxes.Earth.Fixed.FindInAxes(0, (IAgCrdnAxes)axes);
IAgOrientation orientation = result.Orientation;

Array eulerAngles = orientation.QueryEulerAnglesArray(AgEEulerOrientationSequence.e213);
eulerAngles.SetValue((double)eulerAngles.GetValue(0) + Math.PI / 2, 0);
orientation.AssignEulerAngles(AgEEulerOrientationSequence.e213, eulerAngles.GetValue(0), eulerAngles.GetValue(1), eulerAngles.GetValue(2));

model.Orientation = orientation;

A topographic axes is created based on the model's position where the x axis points in the local north direction, the y axis points in the local east direction and the z axis points in the local down direction. An IAgOrientation that defines the rotation from these axes to the fixed frame axes is created. To point the model in the local up direction, the IAgOrientation is modified to rotate an extra 90 degrees around the y axis.

Like orientation, the size of the model depends on the model itself. To change the size of the model, use the Scale property. After a model is initialized, its position can be changed with Position.

COLLADA models also support raster streams. See the Video Streams on Models overview for more information.

Model Articulations

The model primitive supports model articulations, which allow different parts of the model to be rotated, scaled, and/or translated. If the model supports articulations, they can be accessed through the ModelPrimitive's Articulations property.

An example of how to modify a model's articulations is shown below.

The model primitive without modifying the spin ModelTransformation of the propeller's ModelArticulation:

The same model with the spin of the propellers modified to be 135 degrees:

[C#] Copy Code
// Create the model and set the position.
IAgStkGraphicsModelPrimitive model = manager.Initializers.ModelPrimitive.InitializeWithStringUri(modelUri);
Array position = new object[] { 36, -116.75, 25000.0 };
model.SetPositionCartographic("Earth", ref position);

// Modify the roll and yaw of the entire model so that the model appears to be parallel
// with the horizon. This method is only to demonstrate how articulations can be used.
// the preferred method is to set the model's orientation.
model.Articulations.GetByName("Commuter").GetByName("Roll").CurrentValue = 234;
model.Articulations.GetByName("Commuter").GetByName("Yaw").CurrentValue = -25;

// Modify the spin of the propellers.
model.Articulations.GetByName("props").GetByName("Spin").CurrentValue = 135;

The Articulations property of the ModelPrimitive is an instance of ModelArticulationCollection. ModelArticulationCollection contains a collection of ModelArticulations. ModelArticulation contains a collection of ModelTransformations. Both the ModelArticulationCollection and ModelArticulation classes accept an integer index to access its values. Use the ModelTransformation.CurrentValue property to set the value of the transformation as shown in the code above. The Type of transformation can also be retrieved using the ModelTransformation.Type property which returns a value of the ModelTransformationType enumeration.

Advanced Shading

Collada models also support the ColladaFX framework, which allows users to write GLSL code to calculate vertex positions, pixel colors, etc. This allows for models to exhibit lighting properties of materials such as metal, glass, plastic, etc. ColladaFX also allows changing OpenGL States, use of all supported OpenGL Texture types (1D, 2D, 3D, cubemap, rectangle, shadow), and render to texture for use with multipass rendering techniques.

Satellite that uses a metallic BRDF based on the work of Ashikhmin and Shirley. The paper can be found here
This example can be seen in the GraphicsHowTo example under "Primitives" -> "Models" -> "Draw a Collada model with user defined lighting"

Within your shader code, you have access to scene data that is useful for shading your model. We refer to these as Preset Uniforms because they are accessed as uniform variables in your vertex or fragment shader. These variables must be declared as uniforms and then can be used. Here is an example using STK Engine's animation time to move a vertex.

[GLSL] Copy Code
uniform float agi_Time;
uniform float fullOffset;

// Vertex Shader that oscillates from position to position+fullOffset along the Z axis.
void main()
{
     // Get fractional part of time
     float t = fract(agi_Time);

     // Move apply modelview and projection
     vec4 pos = gl_ModelViewProjectionMatrix * gl_Vertex;

     // Move vertex a certain percentage of offset
     pos.z += fullOffset * t;

     // Set position
     gl_Position = pos;
}

Preset Uniforms

Preset Uniform Type Description
agi_ActiveLights bool[gl_MaxLights] Light i is active if agi_ActiveLights[i] is true and inactive if false. Light properties can be accessed through gl_LightSources.
agi_CameraPosition vec3 Position of the camera relative to the model's reference frame.
agi_CentralBodyDepthTexture0,
agi_CentralBodyDepthTexture1,
...,
agi_CentralBodyDepthTexture7		 sampler2D A texture that contains the depth values after rendering the Central Body. The number binds the texture to a particular texture unit. See example image below.
agi_LightingEnabled float 1 if lighting is enabled and 0 otherwise
agi_LODGeometricToleranceOverDistance float When multiplied by the distance from the vertex or fragment to the viewer, the result is the geometric error in world space.
agi_LODNegativeGeometricToleranceOverDistance float Negative of agi_LODGeometricToleranceOverDistance
agi_ModelViewMatrix mat4 Modelview matrix
agi_ModelViewMatrixRelativeToCameraPosition mat4 Modelview matrix relative to the camera position
agi_ModelViewMatrixRelativeToPrimitiveCenter mat4 Modelview matrix relative to the model's center
agi_ModelViewProjectionMatrix mat4 Modelview projection matrix
agi_ModelViewProjectionMatrixRelativeToCameraPosition mat4 Modelview projection matrix relative to the camera position
agi_ModelViewProjectionMatrixRelativeToPrimitiveCenter mat4 Modelview projection matrix relative to the model's center
agi_OrthographicProjectionMatrix mat4 Orthographic projection matrix
agi_PerspectiveProjectionMatrix mat4 Perspective projection matrix
agi_PrimitiveBoundingSphere vec4 The model's bounding sphere relative to the model's reference frame. The structure is xyz components are the position and w is the radius in meters.
agi_PrimitiveBoundingSphereRelativeToCameraPosition vec4 The model's bounding sphere relative to the camera position. The structure is xyz components are the position and w is the radius in meters.
agi_PrimitiveColor vec4 The color of the primitive
agi_SnapshotPixelScale float Scale for when rendering high resolution snap shots. Otherwise it is 1.
agi_TerrainSilhouetteTexture0,
agi_TerrainSilhouetteTexture1,
...,
agi_TerrainSilhouetteTexture7		 sampler2D A texture that contains the silhouette of the terrain. The number binds the texture to a particular texture unit. See example image below.
agi_Time float Number of seconds since the time specified to StartTime property.
agi_Viewport vec4 The viewport in the format (left, bottom, width, height)

Central Body rendered normally Central Body Depth Texture

Example of Terrain Silhouette Texture

OpenGL States

Supported OpenGL States

ColladaFX Element OpenGL State Notes
alpha_func glAlphaFunc  
alpha_test_enable glEnable/glDisable with GL_ALPHA_TEST  
blend_color glBlendColor  
blend_enable glEnable/glDisable with GL_BLEND  
blend_equation glBlendEquation  
blend_equation_separate glBlendEquationSeparate Requires OpenGL 2.0
blend_func glBlendFunc  
blend_func_separate glBlendFuncSeparate Requires OpenGL 1.4
color_mask glColorMask  
cull_face glCullFace  
cull_face_enable glEnable/glDisable with GL_CULL_FACE  
depth_clamp_enable glEnable/glDisable with GL_DEPTH_CLAMP_NV Requires GL 3.2 or GL_ARB_depth_clamp
depth_func glDepthFunc  
depth_mask glDepthMask  
depth_range glDepthRange  
depth_test_enable glEnable/glDisable with GL_DEPTH_TEST  
fog_color glFogfv with GL_FOG_COLOR  
fog_density glFogf with GL_FOG_DENSITY  
fog_enable glEnable/glDisable with GL_FOG  
fog_end glFogf with GL_FOG_END  
fog_mode glFogi with GL_FOG_MODE  
fog_start glFogf with GL_FOG_START  
front_face glFrontFace  
line_smooth_enable glEnable/glDisable with GL_LINE_SMOOTH  
line_stipple glLineStipple  
line_stipple_enable glEnable/glDisable with GL_LINE_STIPPLE  
line_width glLineWidth  
point_size glPointSize  
point_smooth_enable glEnable/glDisable with GL_POINT_SMOOTH  
polygon_mode glPolygonMode Only FRONT_AND_BACK
polygon_offset glPolygonOffset  
polygon_offset_fill_enable glEnable/glDisable with GL_POLYGON_OFFSET_FILL  
scissor glScissor  
scissor_test_enable glEnable/glDisable with GL_SCISSOR_TEST  
shade_model glShadeModel  
stencil_func glStencilFunc  
stencil_func_separate glStencilFuncSeparate Requires OpenGL 2.0
stencil_mask glStencilMask  
stencil_mask_separate glStencilMaskSeparate Requires OpenGL 2.0
stencil_op glStencilOp  
stencil_op_separate glStencilOpSeparate Requires OpenGL 2.0
stencil_test_enable glEnable/glDisable with GL_STENCIL_TEST  
texture1D glBindTexture with GL_TEXTURE_1D  
texture2D glBindTexture with GL_TEXTURE_2D  
texture3D glBindTexture with GL_TEXTURE_3D  
textureCUBE glBindTexture with GL_TEXTURE_CUBE_MAP Requires OpenGL 1.3
textureDEPTH glBindTexture with GL_TEXTURE_2D Used for depth textures.
textureRECT glBindTexture with GL_TEXTURE_RECTANGLE_ARB  

Unsupported OpenGL States

ColladaFX Element Notes
auto_normal_enable  
clip_plane Can be emulated in the fragment shader. Removed from OpenGL 3.2 core.
clip_plane_enable Can be emulated in the fragment shader. Removed from OpenGL 3.2 core.
color_logic_op_enable Rarely used.
color_material Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.
color_material_enable Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.
depth_bounds Only affects performance, not the visual output. Not in core GL, requires EXT_depth_bounds_test.
depth_bounds_enable Only affects performance, not the visual output. Not in core GL, requires EXT_depth_bounds_test.
dither_enable Rarely used.
light_ambient Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_constant_attenuation Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_diffuse Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_enable Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_linear_attenuation Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_model_ambient Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_model_color_control Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_model_local_viewer_enable Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_model_two_side_enable Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_position Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_quadratic_attenuation Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_specular Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_spot_cutoff Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_spot_direction Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
light_spot_exponent Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
lighting_enable Can be emulated in fragment shader. Fixed function lighting was removed from OpenGL 3.2 core.
logic_op Rarely used.
logic_op_enable Rarely used.
material_ambient Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.
material_diffuse Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.
material_emission Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.
material_shininess Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.
material_specular Can be emulated in the fragment shader by implementing a BRDF. Removed from OpenGL 3.2 core.
model_view_matrix Can be emulated in the shader. Removed from OpenGL 3.2 core.
multisample_enable Requires an OpenGL context be created with multisample buffers, which is currently not supported in STK Engine.
normalize_enable This is always enabled.
point_distance_attenuation  
point_fade_threshold_size  
point_size_enable  
point_size_max  
point_size_min  
polygon_offset_line_enable  
polygon_offset_point_enable  
polygon_smooth_enable  
projection_matrix Can be emulated in the shader. Removed from OpenGL 3.2 core.
sample_alpha_to_coverage_enable Requires an OpenGL context be created with multisample buffers, which is currently not supported in STK Engine.
sample_alpha_to_one_enable Requires an OpenGL context be created with multisample buffers, which is currently not supported in STK Engine.
sample_coverage  
sample_coverage_enable  
texture_env_color Can be emulated in the fragment shader. Removed from OpenGL 3.2 core.
texture_env_color Can be emulated in the fragment shader. Removed from OpenGL 3.2 core.
texture_pipeline GLES profile only. GLSL is currently the only supported profile.
texture1D_enable This isn't required when using a texture in a shader. Removed from OpenGL 3.2 core
texture2D_enable This isn't required when using a texture in a shader. Removed from OpenGL 3.2 core
texture3D_enable This isn't required when using a texture in a shader. Removed from OpenGL 3.2 core
textureCUBE_enable This isn't required when using a texture in a shader. Removed from OpenGL 3.2 core
textureDEPTH_enable This isn't required when using a texture in a shader. Removed from OpenGL 3.2 core
textureRECT_enable This isn't required when using a texture in a shader. Removed from OpenGL 3.2 core

Resources
Collada 1.4.1 Specification
GLSL Specification
GLSL Tutorial
BRDF explanation and examples

STK Programming Interface 11.0.1