How to: Use BasicEffect

Article
12/10/2010

This example demonstrates how to create and initialize an instance of BasicEffect, initialize a vertex buffer that can be rendered by BasicEffect, and apply the effect and render the geometry.

Note

The steps described here apply to effects created with the BasicEffect class. In contrast, the Effect class is provided for users who wish to write custom effects. For more information, see How to: Create and Apply Custom Effects.

To use BasicEffect

Using the basic effect class requires a set of world, view, and projection matrices, a vertex buffer, a vertex declaration, and an instance of the BasicEffect class. Declare these objects at the beginning of the game.
```
Matrix worldMatrix;
Matrix viewMatrix;
Matrix projectionMatrix;
VertexPositionNormalTexture[] cubeVertices;
VertexDeclaration basicEffectVertexDeclaration;
VertexBuffer vertexBuffer;
BasicEffect basicEffect;
```

Initialize the world, view, and projection matrices. In this example, a world matrix is created that rotates the geometry 22.5 degrees along the x and y axes. The view matrix is a look-at matrix with a camera position at (0, 0, 5), pointing at the origin. The projection matrix is a perspective projection matrix based on a field of view, specifying a 45-degree field of view, an aspect ratio equal to the client window, and a set of near and far planes.

float tilt = MathHelper.ToRadians( 22.5f );  // 22.5 degree angle
// Use the world matrix to tilt the cube along x and y axes.
worldMatrix = Matrix.CreateRotationX( tilt ) *
    Matrix.CreateRotationY( tilt );

viewMatrix = Matrix.CreateLookAt( new Vector3( 0, 0, 5 ), Vector3.Zero,
    Vector3.Up );

projectionMatrix = Matrix.CreatePerspectiveFieldOfView(
    MathHelper.ToRadians( 45 ),  // 45 degree angle
    (float)graphics.GraphicsDevice.Viewport.Width / (float)graphics.GraphicsDevice.Viewport.Height,
    1.0f, 100.0f );

Initialize BasicEffect to the desired values.

basicEffect = new BasicEffect( graphics.GraphicsDevice, null );
basicEffect.Alpha = 1.0f;
basicEffect.DiffuseColor = new Vector3( 1.0f, 0.0f, 1.0f );
basicEffect.SpecularColor = new Vector3( 0.25f, 0.25f, 0.25f );
basicEffect.SpecularPower = 5.0f;
basicEffect.AmbientLightColor = new Vector3( 0.75f, 0.75f, 0.75f );

basicEffect.DirectionalLight0.Enabled = true;
basicEffect.DirectionalLight0.DiffuseColor = Vector3.One;
basicEffect.DirectionalLight0.Direction = Vector3.Normalize( new Vector3( 1.0f, -1.0f, -1.0f ) );
basicEffect.DirectionalLight0.SpecularColor = Vector3.One;

basicEffect.DirectionalLight1.Enabled = true;
basicEffect.DirectionalLight1.DiffuseColor = new Vector3( 0.5f, 0.5f, 0.5f );
basicEffect.DirectionalLight1.Direction = Vector3.Normalize( new Vector3( -1.0f, -1.0f, 1.0f ) );
basicEffect.DirectionalLight1.SpecularColor = new Vector3( 0.5f, 0.5f, 0.5f );

basicEffect.LightingEnabled = true;

basicEffect.World = worldMatrix;
basicEffect.View = viewMatrix;
basicEffect.Projection = projectionMatrix;

BasicEffect can use the vertex type that is appropriate for the options you will enable for the effect.

If lighting is enabled, the vertex must have a normal.
If vertex colors are enabled, the vertex must have colors.
If texturing is enabled, the vertex must have a texture coordinate.

The following code shows a cube created with vertices of type VertexPositionNormalTexture.

cubeVertices = new VertexPositionNormalTexture[36];

Vector3 topLeftFront = new Vector3( -1.0f, 1.0f, 1.0f );
Vector3 bottomLeftFront = new Vector3( -1.0f, -1.0f, 1.0f );
Vector3 topRightFront = new Vector3( 1.0f, 1.0f, 1.0f );
Vector3 bottomRightFront = new Vector3( 1.0f, -1.0f, 1.0f );
Vector3 topLeftBack = new Vector3( -1.0f, 1.0f, -1.0f );
Vector3 topRightBack = new Vector3( 1.0f, 1.0f, -1.0f );
Vector3 bottomLeftBack = new Vector3( -1.0f, -1.0f, -1.0f );
Vector3 bottomRightBack = new Vector3( 1.0f, -1.0f, -1.0f );

Vector2 textureTopLeft = new Vector2( 0.0f, 0.0f );
Vector2 textureTopRight = new Vector2( 1.0f, 0.0f );
Vector2 textureBottomLeft = new Vector2( 0.0f, 1.0f );
Vector2 textureBottomRight = new Vector2( 1.0f, 1.0f );

Vector3 frontNormal = new Vector3( 0.0f, 0.0f, 1.0f );
Vector3 backNormal = new Vector3( 0.0f, 0.0f, -1.0f );
Vector3 topNormal = new Vector3( 0.0f, 1.0f, 0.0f );
Vector3 bottomNormal = new Vector3( 0.0f, -1.0f, 0.0f );
Vector3 leftNormal = new Vector3( -1.0f, 0.0f, 0.0f );
Vector3 rightNormal = new Vector3( 1.0f, 0.0f, 0.0f );

// Front face.
cubeVertices[0] =
    new VertexPositionNormalTexture(
    topLeftFront, frontNormal, textureTopLeft );
cubeVertices[1] =
    new VertexPositionNormalTexture(
    bottomLeftFront, frontNormal, textureBottomLeft );
cubeVertices[2] =
    new VertexPositionNormalTexture(
    topRightFront, frontNormal, textureTopRight );
cubeVertices[3] =
    new VertexPositionNormalTexture(
    bottomLeftFront, frontNormal, textureBottomLeft );
cubeVertices[4] =
    new VertexPositionNormalTexture(
    bottomRightFront, frontNormal, textureBottomRight );
cubeVertices[5] =
    new VertexPositionNormalTexture(
    topRightFront, frontNormal, textureTopRight );

// Back face.
cubeVertices[6] =
    new VertexPositionNormalTexture(
    topLeftBack, backNormal, textureTopRight );
cubeVertices[7] =
    new VertexPositionNormalTexture(
    topRightBack, backNormal, textureTopLeft );
cubeVertices[8] =
    new VertexPositionNormalTexture(
    bottomLeftBack, backNormal, textureBottomRight );
cubeVertices[9] =
    new VertexPositionNormalTexture(
    bottomLeftBack, backNormal, textureBottomRight );
cubeVertices[10] =
    new VertexPositionNormalTexture(
    topRightBack, backNormal, textureTopLeft );
cubeVertices[11] =
    new VertexPositionNormalTexture(
    bottomRightBack, backNormal, textureBottomLeft );

// Top face.
cubeVertices[12] =
    new VertexPositionNormalTexture(
    topLeftFront, topNormal, textureBottomLeft );
cubeVertices[13] =
    new VertexPositionNormalTexture(
    topRightBack, topNormal, textureTopRight );
cubeVertices[14] =
    new VertexPositionNormalTexture(
    topLeftBack, topNormal, textureTopLeft );
cubeVertices[15] =
    new VertexPositionNormalTexture(
    topLeftFront, topNormal, textureBottomLeft );
cubeVertices[16] =
    new VertexPositionNormalTexture(
    topRightFront, topNormal, textureBottomRight );
cubeVertices[17] =
    new VertexPositionNormalTexture(
    topRightBack, topNormal, textureTopRight );

// Bottom face. 
cubeVertices[18] =
    new VertexPositionNormalTexture(
    bottomLeftFront, bottomNormal, textureTopLeft );
cubeVertices[19] =
    new VertexPositionNormalTexture(
    bottomLeftBack, bottomNormal, textureBottomLeft );
cubeVertices[20] =
    new VertexPositionNormalTexture(
    bottomRightBack, bottomNormal, textureBottomRight );
cubeVertices[21] =
    new VertexPositionNormalTexture(
    bottomLeftFront, bottomNormal, textureTopLeft );
cubeVertices[22] =
    new VertexPositionNormalTexture(
    bottomRightBack, bottomNormal, textureBottomRight );
cubeVertices[23] =
    new VertexPositionNormalTexture(
    bottomRightFront, bottomNormal, textureTopRight );

// Left face.
cubeVertices[24] =
    new VertexPositionNormalTexture(
    topLeftFront, leftNormal, textureTopRight );
cubeVertices[25] =
    new VertexPositionNormalTexture(
    bottomLeftBack, leftNormal, textureBottomLeft );
cubeVertices[26] =
    new VertexPositionNormalTexture(
    bottomLeftFront, leftNormal, textureBottomRight );
cubeVertices[27] =
    new VertexPositionNormalTexture(
    topLeftBack, leftNormal, textureTopLeft );
cubeVertices[28] =
    new VertexPositionNormalTexture(
    bottomLeftBack, leftNormal, textureBottomLeft );
cubeVertices[29] =
    new VertexPositionNormalTexture(
    topLeftFront, leftNormal, textureTopRight );

// Right face. 
cubeVertices[30] =
    new VertexPositionNormalTexture(
    topRightFront, rightNormal, textureTopLeft );
cubeVertices[31] =
    new VertexPositionNormalTexture(
    bottomRightFront, rightNormal, textureBottomLeft );
cubeVertices[32] =
    new VertexPositionNormalTexture(
    bottomRightBack, rightNormal, textureBottomRight );
cubeVertices[33] =
    new VertexPositionNormalTexture(
    topRightBack, rightNormal, textureTopRight );
cubeVertices[34] =
    new VertexPositionNormalTexture(
    topRightFront, rightNormal, textureTopLeft );
cubeVertices[35] =
    new VertexPositionNormalTexture(
    bottomRightBack, rightNormal, textureBottomRight );

vertexBuffer = new VertexBuffer(
    graphics.GraphicsDevice,
    VertexPositionNormalTexture.SizeInBytes * cubeVertices.Length,
    ResourceUsage.None,
    ResourceManagementMode.Automatic
);

vertexBuffer.SetData<VertexPositionNormalTexture>( cubeVertices );

Create a vertex declaration for the type VertexPositionNormalTexture. This vertex declaration will be used in the render loop in the next step.
```
basicEffectVertexDeclaration = new VertexDeclaration(
    graphics.GraphicsDevice, VertexPositionNormalTexture.VertexElements );
```

Call the Effect.Begin to begin applying the BasicEffect. Draw the desired geometry between calls to EffectPass.Begin and EffectPass.End. Call Effect.End to stop application of the technique.

graphics.GraphicsDevice.VertexDeclaration =
    basicEffectVertexDeclaration;

graphics.GraphicsDevice.Vertices[0].SetSource( vertexBuffer, 0, VertexPositionNormalTexture.SizeInBytes );

// This code would go between a device 
// BeginScene-EndScene block.
basicEffect.Begin();
foreach (EffectPass pass in basicEffect.CurrentTechnique.Passes)
{
    pass.Begin();

    graphics.GraphicsDevice.DrawPrimitives(
        PrimitiveType.TriangleList,
        0,
        12
    );

    pass.End();
}
basicEffect.End();

The Complete Example

using System;
using System.Collections.Generic;
using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Audio;
using Microsoft.Xna.Framework.Graphics;
using Microsoft.Xna.Framework.Input;
using Microsoft.Xna.Framework.Storage;
using Microsoft.Xna.Framework.Content;

public class Game1 : Microsoft.Xna.Framework.Game
{
    GraphicsDeviceManager graphics;
    ContentManager content;

    Matrix worldMatrix;
    Matrix viewMatrix;
    Matrix projectionMatrix;
    VertexPositionNormalTexture[] cubeVertices;
    VertexDeclaration basicEffectVertexDeclaration;
    VertexBuffer vertexBuffer;
    BasicEffect basicEffect;

    public Game1()
    {
        graphics = new GraphicsDeviceManager( this );
        content = new ContentManager( Services );
    }

    protected override void Initialize()
    {
        base.Initialize();
    }

    protected override void LoadGraphicsContent( bool loadAllContent )
    {
        InitializeTransform();
        if (loadAllContent)
        {
            InitializeEffect();
            InitializeCube();
        }
    }

    private void InitializeTransform()
    {
        float tilt = MathHelper.ToRadians( 22.5f );  // 22.5 degree angle
        // Use the world matrix to tilt the cube along x and y axes.
        worldMatrix = Matrix.CreateRotationX( tilt ) *
            Matrix.CreateRotationY( tilt );

        viewMatrix = Matrix.CreateLookAt( new Vector3( 0, 0, 5 ), Vector3.Zero,
            Vector3.Up );

        projectionMatrix = Matrix.CreatePerspectiveFieldOfView(
            MathHelper.ToRadians( 45 ),  // 45 degree angle
            (float)graphics.GraphicsDevice.Viewport.Width / (float)graphics.GraphicsDevice.Viewport.Height,
            1.0f, 100.0f );

    }

    private void InitializeEffect()
    {
        basicEffectVertexDeclaration = new VertexDeclaration(
            graphics.GraphicsDevice, VertexPositionNormalTexture.VertexElements );


        basicEffect = new BasicEffect( graphics.GraphicsDevice, null );
        basicEffect.Alpha = 1.0f;
        basicEffect.DiffuseColor = new Vector3( 1.0f, 0.0f, 1.0f );
        basicEffect.SpecularColor = new Vector3( 0.25f, 0.25f, 0.25f );
        basicEffect.SpecularPower = 5.0f;
        basicEffect.AmbientLightColor = new Vector3( 0.75f, 0.75f, 0.75f );

        basicEffect.DirectionalLight0.Enabled = true;
        basicEffect.DirectionalLight0.DiffuseColor = Vector3.One;
        basicEffect.DirectionalLight0.Direction = Vector3.Normalize( new Vector3( 1.0f, -1.0f, -1.0f ) );
        basicEffect.DirectionalLight0.SpecularColor = Vector3.One;

        basicEffect.DirectionalLight1.Enabled = true;
        basicEffect.DirectionalLight1.DiffuseColor = new Vector3( 0.5f, 0.5f, 0.5f );
        basicEffect.DirectionalLight1.Direction = Vector3.Normalize( new Vector3( -1.0f, -1.0f, 1.0f ) );
        basicEffect.DirectionalLight1.SpecularColor = new Vector3( 0.5f, 0.5f, 0.5f );

        basicEffect.LightingEnabled = true;

        basicEffect.World = worldMatrix;
        basicEffect.View = viewMatrix;
        basicEffect.Projection = projectionMatrix;


    }

    private void InitializeCube()
    {

        cubeVertices = new VertexPositionNormalTexture[36];

        Vector3 topLeftFront = new Vector3( -1.0f, 1.0f, 1.0f );
        Vector3 bottomLeftFront = new Vector3( -1.0f, -1.0f, 1.0f );
        Vector3 topRightFront = new Vector3( 1.0f, 1.0f, 1.0f );
        Vector3 bottomRightFront = new Vector3( 1.0f, -1.0f, 1.0f );
        Vector3 topLeftBack = new Vector3( -1.0f, 1.0f, -1.0f );
        Vector3 topRightBack = new Vector3( 1.0f, 1.0f, -1.0f );
        Vector3 bottomLeftBack = new Vector3( -1.0f, -1.0f, -1.0f );
        Vector3 bottomRightBack = new Vector3( 1.0f, -1.0f, -1.0f );

        Vector2 textureTopLeft = new Vector2( 0.0f, 0.0f );
        Vector2 textureTopRight = new Vector2( 1.0f, 0.0f );
        Vector2 textureBottomLeft = new Vector2( 0.0f, 1.0f );
        Vector2 textureBottomRight = new Vector2( 1.0f, 1.0f );

        Vector3 frontNormal = new Vector3( 0.0f, 0.0f, 1.0f );
        Vector3 backNormal = new Vector3( 0.0f, 0.0f, -1.0f );
        Vector3 topNormal = new Vector3( 0.0f, 1.0f, 0.0f );
        Vector3 bottomNormal = new Vector3( 0.0f, -1.0f, 0.0f );
        Vector3 leftNormal = new Vector3( -1.0f, 0.0f, 0.0f );
        Vector3 rightNormal = new Vector3( 1.0f, 0.0f, 0.0f );

        // Front face.
        cubeVertices[0] =
            new VertexPositionNormalTexture(
            topLeftFront, frontNormal, textureTopLeft );
        cubeVertices[1] =
            new VertexPositionNormalTexture(
            bottomLeftFront, frontNormal, textureBottomLeft );
        cubeVertices[2] =
            new VertexPositionNormalTexture(
            topRightFront, frontNormal, textureTopRight );
        cubeVertices[3] =
            new VertexPositionNormalTexture(
            bottomLeftFront, frontNormal, textureBottomLeft );
        cubeVertices[4] =
            new VertexPositionNormalTexture(
            bottomRightFront, frontNormal, textureBottomRight );
        cubeVertices[5] =
            new VertexPositionNormalTexture(
            topRightFront, frontNormal, textureTopRight );

        // Back face.
        cubeVertices[6] =
            new VertexPositionNormalTexture(
            topLeftBack, backNormal, textureTopRight );
        cubeVertices[7] =
            new VertexPositionNormalTexture(
            topRightBack, backNormal, textureTopLeft );
        cubeVertices[8] =
            new VertexPositionNormalTexture(
            bottomLeftBack, backNormal, textureBottomRight );
        cubeVertices[9] =
            new VertexPositionNormalTexture(
            bottomLeftBack, backNormal, textureBottomRight );
        cubeVertices[10] =
            new VertexPositionNormalTexture(
            topRightBack, backNormal, textureTopLeft );
        cubeVertices[11] =
            new VertexPositionNormalTexture(
            bottomRightBack, backNormal, textureBottomLeft );

        // Top face.
        cubeVertices[12] =
            new VertexPositionNormalTexture(
            topLeftFront, topNormal, textureBottomLeft );
        cubeVertices[13] =
            new VertexPositionNormalTexture(
            topRightBack, topNormal, textureTopRight );
        cubeVertices[14] =
            new VertexPositionNormalTexture(
            topLeftBack, topNormal, textureTopLeft );
        cubeVertices[15] =
            new VertexPositionNormalTexture(
            topLeftFront, topNormal, textureBottomLeft );
        cubeVertices[16] =
            new VertexPositionNormalTexture(
            topRightFront, topNormal, textureBottomRight );
        cubeVertices[17] =
            new VertexPositionNormalTexture(
            topRightBack, topNormal, textureTopRight );

        // Bottom face. 
        cubeVertices[18] =
            new VertexPositionNormalTexture(
            bottomLeftFront, bottomNormal, textureTopLeft );
        cubeVertices[19] =
            new VertexPositionNormalTexture(
            bottomLeftBack, bottomNormal, textureBottomLeft );
        cubeVertices[20] =
            new VertexPositionNormalTexture(
            bottomRightBack, bottomNormal, textureBottomRight );
        cubeVertices[21] =
            new VertexPositionNormalTexture(
            bottomLeftFront, bottomNormal, textureTopLeft );
        cubeVertices[22] =
            new VertexPositionNormalTexture(
            bottomRightBack, bottomNormal, textureBottomRight );
        cubeVertices[23] =
            new VertexPositionNormalTexture(
            bottomRightFront, bottomNormal, textureTopRight );

        // Left face.
        cubeVertices[24] =
            new VertexPositionNormalTexture(
            topLeftFront, leftNormal, textureTopRight );
        cubeVertices[25] =
            new VertexPositionNormalTexture(
            bottomLeftBack, leftNormal, textureBottomLeft );
        cubeVertices[26] =
            new VertexPositionNormalTexture(
            bottomLeftFront, leftNormal, textureBottomRight );
        cubeVertices[27] =
            new VertexPositionNormalTexture(
            topLeftBack, leftNormal, textureTopLeft );
        cubeVertices[28] =
            new VertexPositionNormalTexture(
            bottomLeftBack, leftNormal, textureBottomLeft );
        cubeVertices[29] =
            new VertexPositionNormalTexture(
            topLeftFront, leftNormal, textureTopRight );

        // Right face. 
        cubeVertices[30] =
            new VertexPositionNormalTexture(
            topRightFront, rightNormal, textureTopLeft );
        cubeVertices[31] =
            new VertexPositionNormalTexture(
            bottomRightFront, rightNormal, textureBottomLeft );
        cubeVertices[32] =
            new VertexPositionNormalTexture(
            bottomRightBack, rightNormal, textureBottomRight );
        cubeVertices[33] =
            new VertexPositionNormalTexture(
            topRightBack, rightNormal, textureTopRight );
        cubeVertices[34] =
            new VertexPositionNormalTexture(
            topRightFront, rightNormal, textureTopLeft );
        cubeVertices[35] =
            new VertexPositionNormalTexture(
            bottomRightBack, rightNormal, textureBottomRight );

        vertexBuffer = new VertexBuffer(
            graphics.GraphicsDevice,
            VertexPositionNormalTexture.SizeInBytes * cubeVertices.Length,
            ResourceUsage.None,
            ResourceManagementMode.Automatic
        );

        vertexBuffer.SetData<VertexPositionNormalTexture>( cubeVertices );

    }

    protected override void UnloadGraphicsContent( bool unloadAllContent )
    {
        if (unloadAllContent == true)
        {
            content.Unload();
        }
    }

    protected override void Update( GameTime gameTime )
    {
        // Allows the default game to exit on Xbox 360 and Windows.
        if (GamePad.GetState( PlayerIndex.One ).Buttons.Back == ButtonState.Pressed)
            this.Exit();

        base.Update( gameTime );
    }


    protected override void Draw( GameTime gameTime )
    {

        graphics.GraphicsDevice.Clear( Color.CornflowerBlue );

        graphics.GraphicsDevice.RenderState.CullMode =
        CullMode.CullClockwiseFace;

        graphics.GraphicsDevice.VertexDeclaration =
            basicEffectVertexDeclaration;

        graphics.GraphicsDevice.Vertices[0].SetSource( vertexBuffer, 0, VertexPositionNormalTexture.SizeInBytes );

        // This code would go between a device 
        // BeginScene-EndScene block.
        basicEffect.Begin();
        foreach (EffectPass pass in basicEffect.CurrentTechnique.Passes)
        {
            pass.Begin();

            graphics.GraphicsDevice.DrawPrimitives(
                PrimitiveType.TriangleList,
                0,
                12
            );

            pass.End();
        }
        basicEffect.End();

        base.Draw( gameTime );
    }
}

Share via

How to: Use BasicEffect

To use BasicEffect

The Complete Example

Additional resources