Matrix3D structure

Applies to Windows and Windows Phone

Represents a 4 × 4 matrix that is used for transformations in a 3-D space. Used as a value for Matrix3DProjection.ProjectionMatrix.

Syntax


public struct Matrix3D


<Matrix3DProjection ProjectionMatrix="m11, m12, m13, m14, 
  m21, m22, m23, m24, m31, m32, m33, m34, offsetX, offsetY, offsetZ, m44" />



<!--xmlns:m3d="using:Windows.UI.Xaml.Media.Media3D"-->
<m3d:Matrix3D>
m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, offsetX, offsetY, offsetZ, m44
</m3d:Matrix3D>

Attributes

[Version(0x06020000)]
[WebHostHidden()]

Members

The Matrix3D structure has these types of members:

Constructors

The Matrix3D structure has these constructors.

ConstructorDescription
Matrix3D Initializes a new instance of the Matrix3D class.

 

Fields

The Matrix3D structure has these fields.

FieldData typeDescription
M11

System.Double [.NET] | float64 [C++]

The value of the first row and first column of this Matrix3D.

M12

System.Double [.NET] | float64 [C++]

The value of the first row and second column of this Matrix3D.

M13

System.Double [.NET] | float64 [C++]

The value of the first row and third column of this Matrix3D.

M14

System.Double [.NET] | float64 [C++]

The value of the first row and fourth column of this Matrix3D.

M21

System.Double [.NET] | float64 [C++]

The value of the second row and first column of this Matrix3D.

M22

System.Double [.NET] | float64 [C++]

The value of the second row and second column of this Matrix3D.

M23

System.Double [.NET] | float64 [C++]

The value of the second row and third column of this Matrix3D.

M24

System.Double [.NET] | float64 [C++]

The value of the second row and fourth column of this Matrix3D.

M31

System.Double [.NET] | float64 [C++]

The value of the third row and first column of this Matrix3D.

M32

System.Double [.NET] | float64 [C++]

The value of the third row and second column of this Matrix3D.

M33

System.Double [.NET] | float64 [C++]

The value of the third row and third column of this Matrix3D.

M34

System.Double [.NET] | float64 [C++]

The value of the third row and fourth column of this Matrix3D.

M44

System.Double [.NET] | float64 [C++]

The value of the fourth row and fourth column of this Matrix3D.

OffsetX

System.Double [.NET] | float64 [C++]

The value of the fourth row and first column of this Matrix3D.

OffsetY

System.Double [.NET] | float64 [C++]

The value of the fourth row and second column of this Matrix3D.

OffsetZ

System.Double [.NET] | float64 [C++]

The value of the fourth row and third column of this Matrix3D.

 

Methods

The Matrix3D structure has these methods. It also inherits methods from the Object class.

MethodDescription
Equals(Matrix3D) [C#, VB]Compares two Matrix3D structures for equality.
Equals(Object) [C#, VB]Determines whether the specified object is equal to a Matrix3D.
GetHashCode [C#, VB]Gets a hash code for this object.
Invert Inverts this Matrix3D structure.
ToString [C#, VB]Converts a Matrix3D to a String representation.
ToString(IFormatProvider) [C#, VB]Creates a String representation of this Matrix3D.

 

Operators

The Matrix3D structure has these operators.

OperatorDescription
Equality Compares two Matrix3D structures for equality.
Inequality Compares two Matrix3D structures for inequality.
Multiply Multiplies the specified matrices.

 

Properties

The Matrix3D structure has these properties.

PropertyAccess typeDescription

HasInverse

Read-onlyGets a value that indicates whether this Matrix3D is invertible.

Identity

Read-onlyChanges a Matrix3D structure into an identity Matrix3D.

IsIdentity

Read-onlyDetermines whether this Matrix3D structure is an identity Matrix3D.

M11

Read/writeGets or sets the value of the first row and first column of this Matrix3D.

M11

Read/writeGets or sets the value of the first row and first column of this Matrix3D.

M12

Read/writeGets or sets the value of the first row and second column of this Matrix3D.

M13

Read/writeGets or sets the value of the first row and third column of this Matrix3D.

M14

Read/writeGets or sets the value of the first row and fourth column of this Matrix3D.

M21

Read/writeGets or sets the value of the second row and first column of this Matrix3D.

M22

Read/writeGets or sets the value of the second row and second column of this Matrix3D.

M23

Read/writeGets or sets the value of the second row and third column of this Matrix3D.

M24

Read/writeGets or sets the value of the second row and fourth column of this Matrix3D.

M31

Read/writeGets or sets the value of the third row and first column of this Matrix3D.

M32

Read/writeGets or sets the value of the third row and second column of this Matrix3D.

M33

Read/writeGets or sets the value of the third row and third column of this Matrix3D.

M34

Read/writeGets or sets the value of the third row and fourth column of this Matrix3D.

M44

Read/writeGets or sets the value of the fourth row and fourth column of this Matrix3D.

OffsetX

Read/writeGets or sets the value of the fourth row and first column of this Matrix3D.

OffsetY

Read/writeGets or sets the value of the fourth row and second column of this Matrix3D.

OffsetZ

Read/writeGets or sets the value of the fourth row and third column of this Matrix3D.

 

Remarks

You can use the Matrix3DProjection and Matrix3D types for more complex semi–3-D scenarios than are possible with the PlaneProjection type. Matrix3DProjection provides a complete 3-D transform matrix to apply to any UIElement (you use this as a value for the UIElement.Projection property). The matrix lets you apply arbitrary model transform matrices and perspective matrices to visual elements.

Matrix3D has this row-vector syntax:

M11M12M13M14
M21M22M23M24
M31M32M33M34
OffsetXOffsetYOffsetZM44

 

Because the fourth column is accessible, Matrix3D can represent both affine and non-affine transforms.

XAML syntax for Matrix3D

Matrix3D values can be declared in XAML, but the syntax is limited, and different than what you might expect based on how other Windows Runtime structures (like Thickness) support values for XAML UI:

  • The most typical usage for Matrix3D-type properties is to rely on the initialization string behavior that's built-in to the Matrix3D type, and set any value that uses a Matrix3D value as an attribute. You specify a string in the "initialization text" format for constructing a Matrix3D value: 16 separate Double values each separated by comma or space. You can see this format used in the XAML in "Examples" below.
  • There's only one existing property that uses a Matrix3D value: Matrix3DProjection.ProjectionMatrix. So that's what's shown as the primary XAML syntax here.
  • The secondary XAML syntax shown has an actual Matrix3D object element. But note that it has a XAML namespace prefix. The Windows.UI.Xaml.Media.Media3D namespace was not included in the set of code namespaces that the Windows Runtime XAML parser uses for the default XAML namespace. In order to use the Matrix3D as an element in XAML, you have to include an xmlns declaration in your XAML that references Windows.UI.Xaml.Media.Media3D by a using: statement. Then qualify the Matrix3D with the xmlns prefix you mapped for the types in Windows.UI.Xaml.Media.Media3D.
  • Even once you do this mapping, the Matrix3D object element can't have attribute values for setting the 16 properties, it's not enabled by the XAML parser (other XAML structures have special-case handling for properties-as-attribute syntax; Matrix3D happens to not have this). You still have to use the initialization text that sets the 16 values as consecutive atoms of a string. In this case the string is contained as the "inner text" / content of the Matrix3D object element.
  • As you can see the object element syntax isn't any easier to read or use than the inline attribute syntax for Matrix3DProjection.ProjectionMatrix, so the verbose Matrix3D object element syntax isn't common.

Projection and members of Matrix3D

If you are using a Microsoft .NET language (C# or Microsoft Visual Basic), or in Visual C++ component extensions (C++/CX), then Matrix3D has non-data members available, and its data members are exposed as read-write properties, not fields.

If you are programming with C++ using the Windows Runtime Template Library (WRL), then only the data member fields exist as members of Matrix3D, and you cannot use the utility methods or properties listed in the members table. WRL code can access similar utility methods that exist on the Matrix3DHelper class.

Examples

This example uses a simple Matrix3D matrix to transform the image in the X and Y directions when you click the image.


<!-- When you click on the image, the projection is applied. -->
<Image PointerPressed="ApplyProjection" x:Name="BeachImage" Source="guy_by_the_beach.jpg"
       Width="200"/>



private void ApplyProjection(Object sender, PointerRoutedEventArgs e)
{
    Matrix3D m = new Matrix3D();

    // This matrix simply translates the image 100 pixels
    // down and 100 pixels right.
    m.M11 = 1.0; m.M12 = 0.0; m.M13 = 0.0; m.M14 = 0.0;
    m.M21 = 0.0; m.M22 = 1.0; m.M23 = 0.0; m.M24 = 0.0;
    m.M31 = 0.0; m.M32 = 0.0; m.M33 = 1.0; m.M34 = 0.0;
    m.OffsetX = 100; m.OffsetY = 100; m.OffsetZ = 0; m.M44 = 1.0;

    Matrix3DProjection m3dProjection = new Matrix3DProjection();
    m3dProjection.ProjectionMatrix = m;

    BeachImage.Projection = m3dProjection;

}


You can also apply a Matrix3DProjection to an object by using XAML. This example shows how to apply the same transform as the previous example by using XAML instead of code:


<Image Source="guy_by_the_beach.jpg">
    <Image.Projection>
        <Matrix3DProjection  ProjectionMatrix="2, 0, 0, 0,
                                              0, 2, 0, 0,
                                              0, 0, 1, 0,
                                              100, 100, 0, 1"/>
    </Image.Projection>
</Image>


You can multiply matrices together to create more complex effects. This example uses several Matrix3D matrices to apply a 3-D transform to an image so that when you click the image, the 3-D effect is displayed.


<!-- When you click on the image, the projection is applied. -->
<Image PointerPressed="ApplyProjection" x:Name="BeachImage" Source="guy_by_the_beach.jpg" 
       Width="200"/>



private void ApplyProjection(Object sender, PointerRoutedEventArgs e)
{
    // Translate the image along the negative Z-axis such that it occupies 50% of the
    // vertical field of view.
    double fovY = Math.PI / 2.0;
    double translationZ = -BeachImage.ActualHeight / Math.Tan(fovY / 2.0);
    double theta = 20.0 * Math.PI / 180.0;

    // You can create a 3D effect by creating a number of simple 
    // tranformation Matrix3D matrixes and then multiply them together.
    Matrix3D centerImageAtOrigin = TranslationTransform(
             -BeachImage.ActualWidth / 2.0,
             -BeachImage.ActualHeight / 2.0, 0);
    Matrix3D invertYAxis = CreateScaleTransform(1.0, -1.0, 1.0);
    Matrix3D rotateAboutY = RotateYTransform(theta);
    Matrix3D translateAwayFromCamera = TranslationTransform(0, 0, translationZ);
    Matrix3D perspective = PerspectiveTransformFovRH(fovY,
            LayoutRoot.ActualWidth / LayoutRoot.ActualHeight,   // aspect ratio
            1.0,                                                // near plane
            1000.0);                                            // far plane
    Matrix3D viewport = ViewportTransform(LayoutRoot.ActualWidth, LayoutRoot.ActualHeight);

    Matrix3D m = Matrix3DHelper.Multiply(centerImageAtOrigin,invertYAxis);
    m = Matrix3D.Multiply(m ,rotateAboutY);
    m = Matrix3D.Multiply(m,translateAwayFromCamera);
    m = Matrix3D.Multiply(m,perspective);
    m = Matrix3D.Multiply(m,viewport);

    Matrix3DProjection m3dProjection = new Matrix3DProjection();
    m3dProjection.ProjectionMatrix = m;

    BeachImage.Projection = m3dProjection;
}

private Matrix3D TranslationTransform(double tx, double ty, double tz)
{
    Matrix3D m = new Matrix3D();

    m.M11 = 1.0; m.M12 = 0.0; m.M13 = 0.0; m.M14 = 0.0;
    m.M21 = 0.0; m.M22 = 1.0; m.M23 = 0.0; m.M24 = 0.0;
    m.M31 = 0.0; m.M32 = 0.0; m.M33 = 1.0; m.M34 = 0.0;
    m.OffsetX = tx; m.OffsetY = ty; m.OffsetZ = tz; m.M44 = 1.0;

    return m;
}

private Matrix3D CreateScaleTransform(double sx, double sy, double sz)
{
    Matrix3D m = new Matrix3D();

    m.M11 = sx; m.M12 = 0.0; m.M13 = 0.0; m.M14 = 0.0;
    m.M21 = 0.0; m.M22 = sy; m.M23 = 0.0; m.M24 = 0.0;
    m.M31 = 0.0; m.M32 = 0.0; m.M33 = sz; m.M34 = 0.0;
    m.OffsetX = 0.0; m.OffsetY = 0.0; m.OffsetZ = 0.0; m.M44 = 1.0;

    return m;
}

private Matrix3D RotateYTransform(double theta)
{
    double sin = Math.Sin(theta);
    double cos = Math.Cos(theta);

    Matrix3D m = new Matrix3D();

    m.M11 = cos; m.M12 = 0.0; m.M13 = -sin; m.M14 = 0.0;
    m.M21 = 0.0; m.M22 = 1.0; m.M23 = 0.0; m.M24 = 0.0;
    m.M31 = sin; m.M32 = 0.0; m.M33 = cos; m.M34 = 0.0;
    m.OffsetX = 0.0; m.OffsetY = 0.0; m.OffsetZ = 0.0; m.M44 = 1.0;

    return m;
}

private Matrix3D RotateZTransform(double theta)
{
    double cos = Math.Cos(theta);
    double sin = Math.Sin(theta);

    Matrix3D m = new Matrix3D();
    m.M11 = cos; m.M12 = sin; m.M13 = 0.0; m.M14 = 0.0;
    m.M21 = -sin; m.M22 = cos; m.M23 = 0.0; m.M24 = 0.0;
    m.M31 = 0.0; m.M32 = 0.0; m.M33 = 1.0; m.M34 = 0.0;
    m.OffsetX = 0.0; m.OffsetY = 0.0; m.OffsetZ = 0.0; m.M44 = 1.0;
    return m;
}

private Matrix3D PerspectiveTransformFovRH(double fieldOfViewY, double aspectRatio, double zNearPlane, double zFarPlane)
{
    double height = 1.0 / Math.Tan(fieldOfViewY / 2.0);
    double width = height / aspectRatio;
    double d = zNearPlane - zFarPlane;

    Matrix3D m = new Matrix3D();
    m.M11 = width; m.M12 = 0; m.M13 = 0; m.M14 = 0;
    m.M21 = 0; m.M22 = height; m.M23 = 0; m.M24 = 0;
    m.M31 = 0; m.M32 = 0; m.M33 = zFarPlane / d; m.M34 = -1;
    m.OffsetX = 0; m.OffsetY = 0; m.OffsetZ = zNearPlane * zFarPlane / d; m.M44 = 0;

    return m;
}

private Matrix3D ViewportTransform(double width, double height)
{
    Matrix3D m = new Matrix3D();

    m.M11 = width / 2.0; m.M12 = 0.0; m.M13 = 0.0; m.M14 = 0.0;
    m.M21 = 0.0; m.M22 = -height / 2.0; m.M23 = 0.0; m.M24 = 0.0;
    m.M31 = 0.0; m.M32 = 0.0; m.M33 = 1.0; m.M34 = 0.0;
    m.OffsetX = width / 2.0; m.OffsetY = height / 2.0; m.OffsetZ = 0.0; m.M44 = 1.0;

    return m;
}


Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml.Media.Media3D
Windows::UI::Xaml::Media::Media3D [C++]

Metadata

Windows.winmd
Platform.winmd

Assembly

System.Runtime.WindowsRuntime.UI.Xaml.dll

See also

Matrix3DHelper
Matrix3DProjection
UIElement.Projection
3-D perspective effects for XAML UI

 

 

Show:
© 2014 Microsoft