Expand description
WPF-style 3D for FerroUI (#608, docs/porting/media3d.md).
The values of System.Windows.Media.Media3D, with WPF’s names and behaviour and Rust types:
Point3D, Vector3D, Size3D, Rect3D, Point4D, Matrix3D and
Quaternion, with double-precision components (narrowed to single precision only when a
scene is handed to the GPU). Their operators are the traits of std::ops, the members WPF guards
with exceptions return a Result, and each value parses and writes WPF’s text form in the
invariant culture ("0,0,5", "Identity", "Empty"), which is also the form markup writes
them in.
The scene model of Viewport3D, with WPF’s classes and properties:
- the transforms
Transform3D,TranslateTransform3D,ScaleTransform3D,RotateTransform3D,MatrixTransform3DandTransform3DGroup, and the rotationsRotation3D,AxisAngleRotation3DandQuaternionRotation3D; - the cameras
Camera,ProjectionCamera,PerspectiveCamera,OrthographicCameraandMatrixCamera; - the models
Model3D,GeometryModel3DandModel3DGroup, and the lightsLight,AmbientLight,DirectionalLight,PointLightBase,PointLightandSpotLight; - the geometry
Geometry3DandMeshGeometry3D, with the collectionsPoint3DCollection,Vector3DCollectionandInt32Collection(and the base library’sPointsfor the texture coordinates); - the materials
Material,DiffuseMaterial,SpecularMaterial,EmissiveMaterialandMaterialGroup, painting with the brushes of FerroUI; - the visuals
Visual3D,ModelVisual3DandViewport3DVisual, and the controlViewport3D.
A Viewport3DVisual compiles its scene into an immutable Scene3DSnapshot (world
matrices, shared meshes, material layers, lights in world space, the camera with its planes
fitted to the scene, and three generations), which Viewport3D draws through the
render-data operation DrawScene3D; the renderers are in another crate.
register_types adds the classes, the markup metadata of the values and collections (their
text converters) and the XML namespace of the framework to the tables of the markup loader.
Structs§
- Ambient
Light - WPF’s
AmbientLight: light of the same colour everywhere, from no direction. - Axis
Angle Rotation3D - WPF’s
AxisAngleRotation3D: a rotation byAngledegrees aboutAxis, counterclockwise when the axis points at the viewer. An axis of (nearly) zero length is no rotation. - Camera
- WPF’s
Camera: the base of the cameras, with aTransformthat places the camera in the world. - CameraV
Table - The virtual table of the class.
- Diffuse
Material - WPF’s
DiffuseMaterial: itsBrush, filtered byColor, lit by the lights (the ambient lights throughAmbientColor). - Directional
Light - WPF’s
DirectionalLight: parallel light travelling alongDirection((0, 0, -1) by default). - Emissive
Material - WPF’s
EmissiveMaterial: itsBrush, filtered byColor, added without light. - Geometry3D
- WPF’s
Geometry3D: the base of the 3D geometries. - Geometry3DV
Table - The virtual table of the class.
- Geometry
Model3D - WPF’s
GeometryModel3D: aGeometrydrawn withMaterialon its front faces (counterclockwise to the camera) andBackMaterialon its back faces. - Int32
Collection - WPF’s
Int32Collection: the triangle indices of a mesh. Its text form is the numbers separated by white space or commas ("0 1 2","0,1,2"). - Light
- WPF’s
Light: the base of the lights, with aColor(white by default). - Material
- WPF’s
Material: the base of the materials. - Material
Collection - WPF’s
MaterialCollection: the children of aMaterialGroup. - Material
Group - WPF’s
MaterialGroup: itsChildrendrawn in order, each over the ones before. - Matrix3D
- A 4x4 transformation of 3D space, with double-precision elements (WPF’s
System.Windows.Media.Media3D.Matrix3D). - Matrix
Camera - WPF’s
MatrixCamera: the camera of aViewMatrixand aProjectionMatrix. - Matrix
Transform3D - WPF’s
MatrixTransform3D: the transform of itsMatrix. - Mesh
Data - The compiled form of a scene, shared with the renderers (defined by the base library, which the backends depend on). The triangles of a mesh, in single precision, shared by every model and snapshot that draws it.
- Mesh
Geometry3D - WPF’s
MeshGeometry3D:Positions,Normals,TextureCoordinatesandTriangleIndices. - Model3D
- WPF’s
Model3D: the base of the models and the lights. - Model3D
Collection - WPF’s
Model3DCollection: the children of aModel3DGroup. - Model3D
Group - WPF’s
Model3DGroup: itsChildrenunder its transform. - Model3DV
Table - The virtual table of the class.
- Model
Visual3D - WPF’s
ModelVisual3D: shows the model of itsContentand itsChildren. - Orthographic
Camera - WPF’s
OrthographicCamera: a parallel projectionWidthwide (2 by default). - Perspective
Camera - WPF’s
PerspectiveCamera: a perspective projection with a horizontalFieldOfViewin degrees (45 by default). - Point3D
- A location in 3D space, with double-precision coordinates (WPF’s
System.Windows.Media.Media3D.Point3D). - Point3D
Collection - WPF’s
Point3DCollection: the positions of a mesh. Its text form is the points separated by white space, eachx,y,z("0,0,0 1,0,0 0,1,0"). - Point4D
- A point in homogeneous coordinates
(x, y, z, w), with double-precision coordinates (WPF’sSystem.Windows.Media.Media3D.Point4D). APoint3Dis the point withw1; a projectiveMatrix3Dtransforms aPoint4Dwithout the divide byw. - Point
Light - WPF’s
PointLight: light in every direction fromPosition. - Point
Light Base - WPF’s
PointLightBase: light fromPosition, as far asRange(infinite by default), attenuated by1 / (ConstantAttenuation + LinearAttenuation d + QuadraticAttenuation d^2)(1, 0 and 0 by default). - Projection
Camera - WPF’s
ProjectionCamera: a camera atPositionlooking alongLookDirectionwithUpDirectionup, betweenNearPlaneDistanceandFarPlaneDistance. - Quaternion
- A rotation in 3D space, with double-precision components (WPF’s
System.Windows.Media.Media3D.Quaternion):(x, y, z)is the axis scaled by the sine of half the angle,wthe cosine of half the angle. - Quaternion
Rotation3D - WPF’s
QuaternionRotation3D: the rotation of itsQuaternion. - Rect3D
- An axis-aligned box in 3D space: a location (its corner of least coordinates) and a size, with
double-precision values (WPF’s
System.Windows.Media.Media3D.Rect3D). The bounds of the 3D scene model are boxes. - Rotate
Transform3D - WPF’s
RotateTransform3D: the rotation of itsRotationabout the center (CenterX,CenterY,CenterZ). Without a rotation it is the identity. - Rotation3D
- WPF’s
Rotation3D: the base of the rotations. - Rotation3DV
Table - The virtual table of the class.
- Scale
Transform3D - WPF’s
ScaleTransform3D: a scale byScaleX,ScaleYandScaleZabout the center (CenterX,CenterY,CenterZ). - Scene3D
Bounds - The compiled form of a scene, shared with the renderers (defined by the base library, which the backends depend on). An axis-aligned box in single precision: the bounds of a mesh or of a scene.
- Scene3D
Camera - The compiled form of a scene, shared with the renderers (defined by the base library, which the backends depend on). The camera of a snapshot: its matrices for the aspect ratio of the viewport.
- Scene3D
Frame - The compiled form of a scene, shared with the renderers (defined by the base library, which
the backends depend on).
What a drawing context is asked to draw: a snapshot, over
bounds(the viewport in the current coordinates of the context, whose transform maps them to the target). - Scene3D
Material Layer - The compiled form of a scene, shared with the renderers (defined by the base library, which
the backends depend on).
One layer of the material of a model: a
MaterialGroupis flattened into its layers, in order, each drawn over the ones before. - Scene3D
Model - The compiled form of a scene, shared with the renderers (defined by the base library, which
the backends depend on).
A model to draw: a
GeometryModel3Dwith its world matrix and its materials. - Scene3D
Snapshot - The compiled form of a scene, shared with the renderers (defined by the base library, which the backends depend on). An immutable, shared scene: see the documentation of the module.
- Size3D
- The extent of a box in 3D space, with double-precision dimensions (WPF’s
System.Windows.Media.Media3D.Size3D). - Specular
Material - WPF’s
SpecularMaterial: highlights of itsBrush, filtered byColor, as sharp asSpecularPower(40 by default), added to what is below. - Spot
Light - WPF’s
SpotLight: light fromPositionin a cone alongDirection, full insideInnerConeAngle(180 degrees by default) and none beyondOuterConeAngle(90 degrees by default), both full angles in degrees. - Transform3D
- WPF’s
Transform3D: the base of the 3D transforms. - Transform3D
Collection - WPF’s
Transform3DCollection: the children of aTransform3DGroup. - Transform3D
Group - WPF’s
Transform3DGroup: itsChildrenapplied in order (the first one first). - Transform3DV
Table - The virtual table of the class.
- Translate
Transform3D - WPF’s
TranslateTransform3D: a translation byOffsetX,OffsetYandOffsetZ. - Vector3D
- A displacement in 3D space, with double-precision components (WPF’s
System.Windows.Media.Media3D.Vector3D). - Vector3D
Collection - WPF’s
Vector3DCollection: the normals of a mesh, in the text form ofPoint3DCollection. - Viewport3D
- WPF’s
Viewport3D: the scene of itsCameraandChildren(the visuals of aViewport3DVisual, which this control hosts), drawn over its arranged bounds. - Viewport3D
Visual - WPF’s
Viewport3DVisual; see the documentation of the module. - Visual3D
- WPF’s
Visual3D: the base of the 3D visuals, with aTransform. - Visual3D
Collection - WPF’s
Visual3DCollection: the children of aModelVisual3D, aViewport3DVisualand aViewport3D.
Enums§
- Matrix3D
Error - The error of
Matrix3D::invert: the matrix has no inverse (its determinant is zero, within the tolerance ofMatrix3D::has_inverse). WPF throwsInvalidOperationException. - Quaternion
Error - The error of
Quaternion::from_axis_angle: the axis is the zero vector, which names no rotation. WPF throwsInvalidOperationException. - Scene3D
Camera Kind - The compiled form of a scene, shared with the renderers (defined by the base library, which the backends depend on). The kind of the camera a snapshot was made with.
- Scene3D
Change - What a change of a scene object changes in a compiled scene: which generation of the snapshot it bumps.
- Scene3D
Light - The compiled form of a scene, shared with the renderers (defined by the base library, which the backends depend on). A light in world space.
- Scene3D
Material Kind - The compiled form of a scene, shared with the renderers (defined by the base library, which the backends depend on). What a material layer adds to the colour of a model.
- Size3D
Error - The error of the members of
Size3DandRect3Dthat WPF guards: a negative dimension (WPF’sArgumentException), or a change of theEmptyvalue (WPF’sInvalidOperationException).
Statics§
- ASSEMBLY
- What this crate states about itself for markup: its assembly name and the namespaces the XML namespace of the framework maps to (see the documentation of the module for the one name they share with the base library).
Traits§
- Camera
Impl - The overridable members introduced by the class.
- Camera
Impl Ext - Access to the base implementations of the overridable members.
- Geometry3D
Impl - The overridable members introduced by the class.
- Geometry3D
Impl Ext - Access to the base implementations of the overridable members.
- Model3D
Impl - The overridable members introduced by the class.
- Model3D
Impl Ext - Access to the base implementations of the overridable members.
- Rotation3D
Impl - The overridable members introduced by the class.
- Rotation3D
Impl Ext - Access to the base implementations of the overridable members.
- Transform3D
Impl - The overridable members introduced by the class.
- Transform3D
Impl Ext - Access to the base implementations of the overridable members.
Functions§
- register_
types - Registers the namespaces, the classes, the markup metadata and the assembly of this crate (and those of the control library and the base library) with the tables of known types, and the nullable forms of the values and the collections with the untyped value conversions. Cheap and idempotent; nothing is initialised until a type is used.