Chapter 7. Graphics

This chapter provides a reference to and explores the features of the Graphics namespace, which is part of the XNA Framework. The Graphics namespace contains the low-level classes and methods for rendering 3D objects with hardware-accelerated video cards. We will study the Graphics namespace to learn the capabilities of XNA Game Studio with a special emphasis on 3D rendering on the Xbox 360.

Here’s what this chapter will cover:

  • Graphics classes

  • Graphics interfaces

  • Graphics structures

  • Graphics enumerations

Microsoft.Xna.Framework.Graphics Reference

The following pages provide a complete reference to the Graphics namespace, which is the largest of the namespaces in the XNA Framework. This is a great resource because it’s easy to miss the many classes, structures, and events built in to the framework unless one sees a list of those features in a quick reference format, such as this one. As was the case in previous reference chapters, inherited items are omitted from the list of properties, methods, etc., for each item.

Classes

Following are the classes found within the Graphics namespace.

AlphaTestEffect

public class AlphaTestEffect : Effect, IEffectMatrices, IEffectFog

Contains a configurable effect that supports alpha testing.

Public Properties

 

Alpha

Gets or sets the material alpha, which determines its transparency. Range is from 1 (fully opaque) to 0 (fully transparent).

AlphaFunction

Gets or sets the compare function for alpha test. The default value is Greater.

DiffuseColor

Gets or sets the diffuse color for a material. The range of color values is from 0 to 1.

FogColor

Gets or sets the fog color. The range of color values is from 0 to 1.

FogEnabled

Gets or sets the fog enable flag.

FogEnd

Gets or sets the maximum z value for fog, which ranges from 0 to 1.

FogStart

Gets or sets the minimum z value for fog, which ranges from 0 to 1.

Projection

Gets or sets the projection matrix.

ReferenceAlpha

Gets or sets the reference alpha value. The default value is 0.

Texture

Gets or sets the current texture.

VertexColorEnabled

Gets or sets whether vertex color is enabled.

View

Gets or sets the view matrix.

World

Gets or sets the world matrix.

Protected Methods

 

OnApply

Computes derived parameter values immediately before applying the effect using a lazy architecture.

BasicEffect

public class BasicEffect : Effect, IEffectMatrices, IEffectLights, IEffectFog

Contains a basic rendering effect.

Public Properties

 

Alpha

Gets or sets the material alpha, which determines its transparency. Range is from 1 (fully opaque) to 0 (fully transparent).

AmbientLightColor

Gets or sets the ambient color for a light. The range of color values is from 0 to 1.

DiffuseColor

Gets or sets the diffuse color for a material. The range of color values is from 0 to 1.

DirectionalLight0

Gets the first directional light for this effect.

DirectionalLight1

Gets the second directional light for this effect.

DirectionalLight2

Gets the third directional light for this effect.

EmissiveColor

Gets or sets the emissive color for a material. The range of color values is from 0 to 1.

FogColor

Gets or sets the fog color. The range of color values is from 0 to 1.

FogEnabled

Enables fog.

FogEnd

Gets or sets the maximum z value for fog, which ranges from 0 to 1.

FogStart

Gets or sets the minimum z value for fog, which ranges from 0 to 1.

LightingEnabled

Enables lighting for this effect.

PreferPerPixelLighting

Gets or sets a value indicating that per-pixel lighting should be used if it is available for the current adapter. Per-pixel lighting is available if a graphics adapter supports Pixel Shader Model 2.0.

Projection

Gets or sets the projection matrix.

SpecularColor

Gets or sets the specular color for a material. The range of color values is from 0 to 1.

SpecularPower

Gets or sets the specular power of this effect material.

Texture

Gets or sets a texture to be applied by this effect.

TextureEnabled

Enables textures for this effect.

VertexColorEnabled

Enables the use of vertex colors for this effect.

View

Gets or sets the view matrix.

World

Gets or sets the world matrix.

Public Methods

 

EnableDefaultLighting

Enables default lighting for this effect.

Protected Methods

 

OnApply

Computes derived parameter values immediately before applying the effect.

BlendState

public class BlendState : GraphicsResource

Contains the blend state for the device.

Public Fields

 

Additive

A built-in state object with settings for additive blend (that is, adding the destination data to the source data without using alpha).

AlphaBlend

A built-in state object with settings for alpha blend (that is, blending the source and destination data using alpha).

NonPremultiplied

A built-in state object with settings for blending with non-premultipled alpha (that is, blending source and destination data using alpha while assuming the color data contains no alpha information).

Opaque

A built-in state object with settings for opaque blend (that is, overwriting the source with the destination data).

Public Properties

 

AlphaBlendFunction

Gets or sets the arithmetic operation when blending alpha values. The default is BlendFunction.Add.

AlphaDestinationBlend

Gets or sets the blend factor for the destination alpha, which is the percentage of the destination alpha included in the blended result. The default is Blend.One.

AlphaSourceBlend

Gets or sets the alpha blend factor. The default is Blend.One.

BlendFactor

Gets or sets the four-component (RGBA) blend factor for alpha blending.

ColorBlendFunction

Gets or sets the arithmetic operation when blending color values. The default is BlendFunction.Add.

ColorDestinationBlend

Gets or sets the blend factor for the destination color. The default is Blend.One.

ColorSourceBlend

Gets or sets the blend factor for the source color. The default is Blend.One.

ColorWriteChannels

Gets or sets which color channels (RGBA) are enabled for writing during color blending. The default value is ColorWriteChannels.None.

ColorWriteChannels1

Gets or sets which color channels (RGBA) are enabled for writing during color blending. The default value is ColorWriteChannels.None.

ColorWriteChannels2

Gets or sets which color channels (RGBA) are enabled for writing during color blending. The default value is ColorWriteChannels.None.

ColorWriteChannels3

Gets or sets which color channels (RGBA) are enabled for writing during color blending. The default value is ColorWriteChannels.None.

MultiSampleMask

Gets or sets a bitmask, which defines which samples can be written during multisampling. The default is 0xffffffff.

DepthStencilState

public class DepthStencilState : GraphicsResource

Contains the depth-stencil state for the device.

Public Fields

 

Default

A built-in state object with default settings for using a depth-stencil buffer.

DepthRead

A built-in state object with settings for enabling a read-only depth-stencil buffer.

None

A built-in state object with settings for not using a depth-stencil buffer.

Public Properties

 

CounterClockwiseStencilDepthBufferFail

Gets or sets the stencil operation to perform if the stencil test passes and the depth-buffer test fails for a counterclockwise triangle. The default is StencilOperation.Keep.

CounterClockwiseStencilFail

Gets or sets the stencil operation to perform if the stencil test fails for a counterclockwise triangle. The default is StencilOperation.Keep.

CounterClockwiseStencilFunction

Gets or sets the comparison function to use for counterclockwise stencil tests. The default is CompareFunction.Always.

CounterClockwiseStencilPass

Gets or sets the stencil operation to perform if the stencil and depth tests pass for a counterclockwise triangle. The default is StencilOperation.Keep.

DepthBufferEnable

Enables or disables depth buffering. The default is true.

DepthBufferFunction

Gets or sets the comparison function for the depth-buffer test. The default is CompareFunction.LessEqual.

DepthBufferWriteEnable

Enables or disables writing to the depth buffer. The default is true.

ReferenceStencil

Specifies a reference value to use for the stencil test. The default is 0.

StencilDepthBufferFail

Gets or sets the stencil operation to perform if the stencil test passes and the depth test fails. The default is StencilOperation.Keep.

StencilEnable

Gets or sets stencil enabling. The default is false.

StencilFail

Gets or sets the stencil operation to perform if the stencil test fails. The default is StencilOperation.Keep.

StencilFunction

Gets or sets the comparison function for the stencil test. The default is CompareFunction.Always.

StencilMask

Gets or sets the mask applied to the reference value and each stencil-buffer entry to determine the significant bits for the stencil test. The default mask is Int32.MaxValue.

StencilPass

Gets or sets the stencil operation to perform if the stencil test passes. The default is StencilOperation.Keep.

StencilWriteMask

Gets or sets the write mask applied to values written into the stencil buffer. The default mask is Int32.MaxValue.

TwoSidedStencilMode

Enables or disables two-sided stenciling. The default is false.

DeviceLostException

public sealed class DeviceLostException : Exception

This exception is thrown when the device has been lost but cannot be reset at this time. Therefore, rendering is not possible.

DeviceNotResetException

public sealed class DeviceNotResetException : Exception

This exception is thrown when the device has been lost but can be reset at this time.

DirectionalLight

public sealed class DirectionalLight

Creates a DirectionalLight object.

Public Properties

 

DiffuseColor

Gets or sets the diffuse color of the light.

Direction

Gets or sets the light direction. This value must be a unit vector.

Enabled

Gets or sets light enable flag.

SpecularColor

Gets or sets the specular color of the light.

DisplayMode

public class DisplayMode

Describes the display mode.

Public Properties

 

AspectRatio

Gets the aspect ratio used by the graphics device.

Format

Gets a value indicating the surface format of the display mode.

Height

Gets a value indicating the screen height, in pixels.

TitleSafeArea

Returns the title safe area of the display.

Width

Gets a value indicating the screen width, in pixels.

DisplayModeCollection

public class DisplayModeCollection : IEnumerable<DisplayMode>, IEnumerable

Manipulates a collection of DisplayMode structures.

Public Properties

 

Item

Retrieves the DisplayMode structure with the specified format.

Public Methods

 

GetEnumerator

Gets an enumerator that can iterate through the DisplayModeCollection.

DualTextureEffect

public class DualTextureEffect : Effect, IEffectMatrices, IEffectFog

Contains a configurable effect that supports two-layer multitexturing.

Public Properties

 

Alpha

Gets or sets the material alpha, which determines its transparency. Range is from 1 (fully opaque) to 0 (fully transparent).

DiffuseColor

Gets or sets the diffuse color for a material. The range of color values is from 0 to 1.

FogColor

Gets or sets the fog color. The range of color values is from 0 to 1.

FogEnabled

Gets or sets the fog enable flag.

FogEnd

Gets or sets the maximum z value for fog, which ranges from 0 to 1.

FogStart

Gets or sets the minimum z value for fog, which ranges from 0 to 1.

Projection

Gets or sets the projection matrix.

Texture

Gets or sets the current base texture.

Texture2

Gets or sets the current overlay texture.

VertexColorEnabled

Gets or sets whether per-vertex color is enabled.

View

Gets or sets the view matrix.

World

Gets or sets the world matrix.

Protected Methods

 

OnApply

Computes derived parameter values immediately before applying the effect.

DynamicIndexBuffer

public class DynamicIndexBuffer : IndexBuffer

Describes the rendering order of the vertices in a vertex buffer.

Public Properties

 

IsContentLost

Determines whether the index buffer data has been lost due to a lost-device event.

Public Methods

 

SetData

Copies array data to the index buffer.

Public Events

 

ContentLost

Occurs when resources are lost due to a lost-device event.

DynamicVertexBuffer

public class DynamicVertexBuffer : VertexBuffer

Represents a list of 3D vertices to be streamed to the graphics device. In situations where your game frequently modifies a vertex buffer, it is recommended that the buffer be instantiated or derived from DynamicVertexBuffer instead of the VertexBuffer class. DynamicVertexBuffer is optimized for frequent vertex data modification. However, to fully maximize the benefits of this class, your data must be restored after any occurrence of a ContentLost event. This event occurs whenever the related graphics device is lost. After resetting the graphics device and restoring any static resources, the ContentLost event handler is then called. Calling SetData inside this handler restores any dynamic resource data.

Public Properties

 

IsContentLost

Determines whether the index buffer data has been lost due to a lost-device event.

Public Methods

 

SetData

Copies array data to the vertex buffer.

Public Events

 

ContentLost

Occurs when resources are lost due to a lost-device event.

Effect

public class Effect : GraphicsResource

Used to set and query effects, and to choose techniques.

Public Properties

 

CurrentTechnique

Gets or sets the active technique.

Parameters

Gets a collection of parameters used for this effect.

Techniques

Gets a collection of techniques that are defined for this effect.

Protected Methods

 

OnApply

Applies the effect state just prior to rendering the effect.

EffectAnnotation

public sealed class EffectAnnotation

Represents an annotation to an EffectParameter.

Public Properties

 

ColumnCount

Gets the number of columns in this effect annotation.

Name

Gets the name of the effect annotation.

ParameterClass

Gets the parameter class of this effect annotation.

ParameterType

Gets the parameter type of this effect annotation.

RowCount

Gets the row count of this effect annotation.

Semantic

Gets the semantic of this effect annotation.

Public Methods

 

GetValueBoolean

Gets the value of the EffectAnnotation as a Boolean.

GetValueInt32

Gets the value of the EffectAnnotation as an Int32.

GetValueMatrix

Gets the value of the EffectAnnotation as an Int32.

GetValueSingle

Gets the value of the EffectAnnotation as a Single.

GetValueString

Gets the value of the EffectAnnotation as a String.

GetValueVector2

Gets the value of the EffectAnnotation as a Vector2.

GetValueVector3

Gets the value of the EffectAnnotation as a Vector3.

GetValueVector4

Gets the value of the EffectAnnotation as a Vector4.

EffectAnnotationCollection

public sealed class EffectAnnotationCollection : IEnumerable<EffectAnnotation>

Manipulates a collection of EffectAnnotation objects.

Public Properties

 

Count

Gets the number of EffectAnnotation objects in this EffectAnnotationCollection.

Item

Gets an EffectAnnotation object.

Public Methods

 

GetEnumerator

Gets an enumerator that can iterate through the EffectAnnotationCollection.

Explicit Interface Implementations

 

System.Collections.IEnumerable.GetEnumerator

Gets an enumerator that can iterate through the EffectAnnotationCollection.

System.Collections.Generic.IEnumerable{T}.GetEnumerator

Gets an enumerator that can iterate through the EffectAnnotationCollection.

EffectMaterial

public class EffectMaterial : Effect

Contains an effect subclass that is used to load data for an EffectMaterialContent type. For most purposes, this type can be ignored, and treated exactly like a regular effect. When an EffectMaterial type is loaded from XNB format, its parameter values and textures are also loaded and automatically set on the effect, in addition to the HLSL shader code. Use this class to write a content pipeline extension to store materials inside a custom data type.

EffectParameter

public sealed class EffectParameter

Represents an Effect parameter. Creating and assigning an EffectParameter instance for each technique in your Effect is significantly faster than using the Parameters indexed property on Effect.

Public Properties

 

Annotations

Gets the collection of EffectAnnotation objects for this parameter.

ColumnCount

Gets the number of columns in the parameter description.

Elements

Gets the collection of effect parameters.

Name

Gets the name of the parameter.

ParameterClass

Gets the class of the parameter.

ParameterType

Gets the type of the parameter.

RowCount

Gets the number of rows in the parameter description.

Semantic

Gets the semantic meaning, or usage, of the parameter.

StructureMembers

Gets the collection of structure members.

Public Methods

 

GetValueBoolean

Gets the value of the EffectParameter as a Boolean.

GetValueBooleanArray

Gets the value of the EffectParameter as an array of Boolean.

GetValueInt32

Gets the value of the EffectParameter as an Int32.

GetValueInt32Array

Gets the value of the EffectParameter as an array of Int32.

GetValueMatrix

Gets the value of the EffectParameter as a Matrix.

GetValueMatrixArray

Gets the value of the EffectParameter as an array of Matrix.

GetValueMatrixTranspose

Gets the value of the EffectParameter as a Matrix transpose.

GetValueMatrixTransposeArray

Gets the value of the EffectParameter as an array of Matrix transpose.

GetValueQuaternion

Gets the value of the EffectParameter as a Quaternion.

GetValueQuaternionArray

Gets the value of the EffectParameter as an array of Quaternion.

GetValueSingle

Gets the value of the EffectParameter as a Single.

GetValueSingleArray

Gets the value of the EffectParameter as an array of Single.

GetValueString

Gets the value of the EffectParameter as a String.

GetValueTexture2D

Gets the value of the EffectParameter as a Texture2D.

GetValueTexture3D

Gets the value of the EffectParameter as a Texture3D.

GetValueTextureCube

Gets the value of the EffectParameter as a TextureCube.

GetValueVector2

Gets the value of the EffectParameter as a Vector2.

GetValueVector2Array

Gets the value of the EffectParameter as an array of Vector2.

GetValueVector3

Gets the value of the EffectParameter as a Vector3.

GetValueVector3Array

Gets the value of the EffectParameter as an array of Vector3.

GetValueVector4

Gets the value of the EffectParameter as a Vector4.

GetValueVector4Array

Gets the value of the EffectParameter as an array of Vector4.

SetValue

Sets the value of the EffectParameter.

SetValueTranspose

Sets the value of the EffectParameter.

EffectParameterCollection

public sealed class EffectParameter

Manipulates a collection of EffectParameter objects. Creating and assigning an EffectParameter instance for each technique in your Effect is significantly faster than using the Parameters indexed property on Effect.

Public Properties

 

Count

Gets the number of EffectParameter objects in this EffectParameterCollection.

Item

Gets an EffectParameter object.

Public Methods

 

GetEnumerator

Gets an enumerator that can iterate through EffectParameterCollection.

GetParameterBySemantic

Gets an effect parameter from its semantic usage.

Explicit Interface Implementations

 

System.Collections.IEnumerable.GetEnumerator

Gets an enumerator that can iterate through EffectParameterCollection.

System.Collections.Generic.IEnumerable{T}.GetEnumerator

Gets an enumerator that can iterate through EffectParameterCollection.

EffectPass

public sealed class EffectPass

Contains the rendering state for drawing with an effect; an effect can contain one or more passes.

Public Properties

 

Annotations

Gets the set of EffectAnnotation objects for this EffectPass.

Name

Gets the name of this pass.

Public Methods

 

Apply

Begins this pass.

EffectPassCollection

public sealed class EffectPassCollection : IEnumerable<EffectPass>

Manipulates a collection of EffectPass objects.

Public Properties

 

Count

Gets the number of objects in the collection.

Item

Gets an element in the collection.

Public Methods

 

GetEnumerator

Gets an enumerator that can iterate through the EffectPassCollection.

Explicit Interface Implementations

 

System.Collections.IEnumerable.GetEnumerator

Gets an enumerator that can iterate through the EffectPassCollection.

System.Collections.Generic.IEnumerable{T}.GetEnumerator

Gets an enumerator that can iterate through the EffectPassCollection.

EffectTechnique

public sealed class EffectTechnique

Represents an effect technique. Creating and assigning an EffectTechnique instance for each technique in your Effect is significantly faster than using the Techniques indexed property on Effect.

Public Properties

 

Annotations

Gets the EffectAnnotation objects associated with this technique.

Name

Gets the name of this technique.

Passes

Gets the collection of EffectPass objects this rendering technique requires.

EffectTechniqueCollection

public sealed class EffectTechniqueCollection : IEnumerable<EffectTechnique>

Manipulates a collection of EffectTechnique objects.

Public Properties

 

Count

Gets the number of objects in the collection.

Item

Gets an element in the collection.

Public Methods

 

GetEnumerator

Gets an enumerator that can iterate through the EffectTechniqueCollection.

Explicit Interface Implementations

 

System.Collections.IEnumerable.GetEnumerator

Gets an enumerator that can iterate through the EffectTechniqueCollection.

System.Collections.Generic.IEnumerable{T}.GetEnumerator

Gets an enumerator that can iterate through the EffectTechniqueCollection.

EnvironmentMapEffect

public class EnvironmentMapEffect : Effect, IEffectMatrices, IEffectLights, IEffectFog

Contains a configurable effect that supports environment mapping.

Public Properties

 

Alpha

Gets or sets the material alpha, which determines its transparency. Range is between 1 (fully opaque) and 0 (fully transparent).

AmbientLightColor

Gets or sets the ambient color for a light. The range of color values is from 0 to 1.

DiffuseColor

Gets or sets the diffuse color for a material. The range of color values is from 0 to 1.

DirectionalLight0

Gets the first directional light.

DirectionalLight1

Gets the second directional light.

DirectionalLight2

Gets the third directional light.

EmissiveColor

Gets or sets the emissive color for a material. The range of color values is from 0 to 1.

EnvironmentMap

Gets or sets the current environment map texture.

EnvironmentMapAmount

Gets or sets the amount of the environment map color (RGB) that will be blended over the base texture. The value ranges from 0 to 1; the default value is 1.

EnvironmentMapSpecular

Gets or sets the amount of the environment map alpha value that will be added to the base texture. The value ranges from 0 to 1; the default value is 0.

FogColor

Gets or sets the fog color. The range of color values is from 0 to 1.

FogEnabled

Gets or sets the fog enable flag.

FogEnd

Gets or sets the maximum z value for fog, which ranges from 0 to 1.

FogStart

Gets or sets the minimum z value for fog, which ranges from 0 to 1.

FresnelFactor

Gets or sets the Fresnel factor used for the environment map blending.

Projection

Gets or sets the projection matrix.

Texture

Gets or sets the current texture.

View

Gets or sets the view matrix.

World

Gets or sets the world matrix.

Public Methods

 

EnableDefaultLighting

Sets up standard key, fill, and back lighting for an EnvironmentMapEffect.

Protected Methods

 

OnApply

Computes derived parameter values immediately before applying the effect.

Explicit Interface Implementations

LightingEnabled Property

Enables lighting in an EnvironmentMapEffect.

GraphicsAdapter

public sealed class GraphicsAdapter

Provides methods to retrieve and manipulate graphics adapters.

Public Properties

 

Adapters

Collection of available adapters on the system.

CurrentDisplayMode

Gets the current display mode.

DefaultAdapter

Gets the default adapter.

Description

Retrieves a string used for presentation to the user.

DeviceId

Retrieves a value that is used to help identify a particular chip set.

DeviceName

Retrieves a string that contains the device name for a Microsoft Windows Graphics Device Interface (GDI).

IsDefaultAdapter

Determines whether this instance of GraphicsAdapter is the default adapter.

IsWideScreen

Determines whether the graphics adapter is in widescreen mode.

MonitorHandle

Retrieves the handle of the monitor associated with the Microsoft Direct3D object.

Revision

Retrieves a value used to help identify the revision level of a particular chip set.

SubSystemId

Retrieves a value used to identify the subsystem.

SupportedDisplayModes

Returns a collection of supported display modes for the current adapter.

UseNullDevice

Gets or sets a null device.

UseReferenceDevice

Gets or sets a reference device.

VendorId

Retrieves a value used to identify the manufacturer.

Public Methods

 

IsProfileSupported

Tests to see whether the adapter supports the requested profile.

QueryBackBufferFormat

Queries the adapter for support for the requested back-buffer format.

QueryRenderTargetFormat

Queries the adapter for support for the requested render target format.

GraphicsDevice

public class GraphicsDevice : IDisposable

Performs primitive-based rendering, creates resources, handles system-level variables, adjusts gamma ramp levels, and creates shaders.

Public Properties

 

Adapter

Gets the graphics adapter.

BlendFactor

Gets or sets the color used for a constant-blend factor during alpha blending. The default value is Color.White.

BlendState

Gets or sets a system-defined instance of a blend state object initialized for alpha blending. The default value is BlendState.Opaque.

DepthStencilState

Gets or sets a system-defined instance of a depth-stencil state object. The default value is DepthStencilState.Default.

DisplayMode

Retrieves the display mode’s spatial resolution, color resolution, and refresh frequency.

GraphicsDeviceStatus

Retrieves the status of the device.

GraphicsProfile

Gets the graphics profile. The default value is GraphicsProfile.Reach.

Indices

Gets or sets index data. The default value is null.

MultiSampleMask

Gets or sets a bitmask controlling modification of the samples in a multisample render target. The default value is –1 (0xffffffff).

PresentationParameters

Gets the presentation parameters associated with this graphics device.

RasterizerState

Gets or sets rasterizer state. The default value is RasterizerState. CullCounterClockwise.

ReferenceStencil

Gets or sets a reference value for stencil testing. The default value is 0.

SamplerStates

Retrieves a collection of SamplerState objects for the current GraphicsDevice.

ScissorRectangle

Gets or sets the rectangle used for scissor testing. By default, the size matches the render target size.

Textures

Returns the collection of textures that have been assigned to the texture stages of the device.

VertexSamplerStates

Gets the collection of vertex sampler states.

VertexTextures

Gets the collection of vertex textures that support texture lookup in the vertex shader using the texldl statement. The vertex engine contains four texture sampler stages.

Viewport

Gets or sets a viewport identifying the portion of the render target to receive draw calls.

Public Methods

 

Clear

Clears resource buffers.

DrawIndexedPrimitives

Renders the specified geometric primitive, based on indexing into an array of vertices.

DrawInstancedPrimitives

Draws a series of instanced models.

DrawPrimitives

Renders a sequence of non-indexed geometric primitives of the specified type from the current set of data-input streams.

DrawUserIndexedPrimitives

Renders geometric primitives with an index.

DrawUserPrimitives

Renders geometric primitives.

GetBackBufferData

Gets the contents of the back buffer.

GetRenderTargets

Gets a render target surface.

GetVertexBuffers

Gets the vertex buffers.

Present

Presents the display with the contents of the next buffer in the sequence of back buffers owned by the GraphicsDevice.

Reset

Resets the presentation parameters for the current GraphicsDevice.

SetRenderTarget

Sets a new color buffer for a GraphicsDevice.

SetRenderTargets

Sets an array of render targets.

SetVertexBuffer

Sets or binds a vertex buffer to a device.

SetVertexBuffers

Sets the vertex buffers.

Public Events

 

DeviceLost

Occurs when a GraphicsDevice is about to be lost (for example, immediately before a reset).

DeviceReset

Occurs after a GraphicsDevice is reset, allowing an application to recreate all resources.

DeviceResetting

Occurs when a GraphicsDevice is resetting, allowing the application to cancel the default handling of the reset.

ResourceCreated

Occurs when a resource is created.

ResourceDestroyed

Occurs when a resource is destroyed.

GraphicsResource

public abstract class GraphicsResource : IDisposable

Queries and prepares resources.

Public Properties

 

GraphicsDevice

Gets the GraphicsDevice associated with this GraphicsResource.

Name

Gets the name of the resource.

Tag

Gets the resource tags for this resource.

IndexBuffer

public class IndexBuffer : GraphicsResource

Describes the rendering order of the vertices in a vertex buffer. The vertex stream and index data of the graphics device must be set before any call to DrawIndexedPrimitives. It associates a user-created vertex buffer of type VertexPositionNormalTexture with vertex stream 0 (zero) of the graphics device.

Public Properties

 

BufferUsage

Gets the state of the related BufferUsage enumeration.

IndexCount

Gets the number of indices in this buffer.

IndexElementSize

Gets a value indicating the size of this index element.

Public Methods

 

GetData

Gets the index buffer into an array.

SetData

Copies array data to the index buffer.

Model

public sealed class Model

Represents a 3D model composed of multiple ModelMesh objects, which may be moved independently.

Public Properties

 

Bones

Gets a collection of ModelBone objects, which describe how each mesh in the Meshes collection for this model relates to its parent mesh.

Meshes

Gets a collection of ModelMesh objects, which compose the model. Each ModelMesh in a model may be moved independently and may be composed of multiple materials identified as ModelMeshPart objects.

Root

Gets the root bone for this model.

Tag

Gets or sets an object identifying this model.

Public Methods

 

CopyAbsoluteBoneTransformsTo

Copies a transform of each bone in a model relative to all parent bones of the bone into a given array.

CopyBoneTransformsFrom

Copies an array of transforms into each bone in the model.

CopyBoneTransformsTo

Copies each bone transform relative only to the parent bone of the model to a given array.

Draw

Renders a model after applying the matrix transformations.

ModelBone

public sealed class ModelBone

Represents bone data for a model. A model bone is a matrix that represents the position of a mesh as it relates to other meshes in a 3D model. A complex computer-generated object, often called a model, is made up of many vertices and materials organized into a set of meshes. In the XNA Framework, a model is represented by the Model class. A model contains one or more meshes, each of which is represented by a ModelMesh class. Each mesh is associated with one bone represented by the ModelBone class.

Public Properties

 

Children

Gets a collection of bones that are children of this bone.

Index

Gets the index of this bone in the Bones collection.

Name

Gets the name of this bone.

Parent

Gets the parent of this bone.

Transform

Gets or sets the matrix used to transform this bone relative to its parent bone.

ModelBoneCollection

public sealed class ModelBoneCollection : ReadOnlyCollection<ModelBone>

Represents a set of bones associated with a model.

Public Properties

 

Item

Retrieves a ModelBone from the collection.

Public Methods

 

GetEnumerator

Returns a ModelBoneCollection.Enumerator that can iterate through a ModelBoneCollection.

TryGetValue

Finds a bone with a given name if it exists in the collection.

ModelEffectCollection

public sealed class ModelEffectCollection : ReadOnlyCollection<Effect>

Represents a collection of effects associated with a model.

Public Methods

 

GetEnumerator

Returns a ModelEffectCollection.Enumerator that can iterate through a ModelEffectCollection.

ModelMesh

public sealed class ModelMesh

Represents a mesh that is part of a Model.

Public Properties

 

BoundingSphere

Gets the BoundingSphere that contains this mesh.

Effects

Gets a collection of effects associated with this mesh.

MeshParts

Gets the ModelMeshPart objects that make up this mesh. Each part of a mesh is composed of a set of primitives that share the same material.

Name

Gets the name of this mesh.

ParentBone

Gets the parent bone for this mesh. The parent bone of a mesh contains a transformation matrix that describes how the mesh is located relative to any parent meshes in a model.

Tag

Gets or sets an object identifying this mesh.

Public Methods

 

Draw

Draws all the ModelMeshPart objects in this mesh, using their current Effect settings.

ModelMeshCollection

public sealed class ModelMeshCollection : ReadOnlyCollection<ModelMesh>

Represents a collection of ModelMesh objects.

Public Properties

 

Item

Retrieves a ModelMesh from the collection.

Public Methods

 

GetEnumerator

Returns a ModelMeshCollection.Enumerator that can iterate through a ModelMeshCollection.

TryGetValue

Finds a mesh with a given name if it exists in the collection.

ModelMeshPart

class definition

Represents a batch of geometry information to submit to the graphics device during rendering. Each ModelMeshPart is a subdivision of a ModelMesh object. The ModelMesh class is split into multiple ModelMeshPart objects, typically based on material information. It is not necessary to use this class directly. In advanced rendering scenarios, it is possible to draw using ModelMeshPart properties in combination with the vertex and index buffers on ModelMesh. However, in most cases, ModelMesh.Draw will be sufficient.

Public Properties

 

Effect

Gets or sets the material Effect for this mesh part.

IndexBuffer

Gets the index buffer for this mesh part.

NumVertices

Gets the number of vertices used during a Draw call.

PrimitiveCount

Gets the number of primitives to render.

StartIndex

Gets the location in the index array at which to start reading vertices.

Tag

Gets or sets an object identifying this model mesh part.

VertexBuffer

Gets the vertex buffer for this mesh part.

VertexOffset

Gets the offset (in vertices) from the top of vertex buffer.

ModelMeshPartCollection

public sealed class ModelMeshPartCollection : ReadOnlyCollection<ModelMeshPart>

Represents a collection of ModelMeshPart objects.

Public Methods

 

GetEnumerator

Returns a ModelMeshPartCollection.Enumerator that can iterate through a ModelMeshPartCollection.

NoSuitableGraphicsDeviceException

public sealed class NoSuitableGraphicsDeviceException : Exception

Thrown when no available graphics device fits the given device preferences.

OcclusionQuery

public class OcclusionQuery : GraphicsResource

Used to perform an occlusion query against the latest drawn objects. An occlusion query is a technique that determines how many pixels were actually drawn during a set of Draw calls. This is useful for certain rendering techniques and rendering optimizations. The number of non-occluded pixels (indicated by PixelCount) can differ based on the platform.

For Xbox 360 games, PixelCount represents the number of pixels modified by drawing. This includes GraphicsDevice.Clear calls and any drawing associated with sprite batches.

For Windows games, PixelCount represents the number of pixels that passed the depth and stencil tests. This does not include sprite-batch drawing (because the depth test is turned off) or calls to GraphicsDevice.Clear.

To achieve consistent results across all platforms, use occlusion queries only when the depth buffer is enabled. In addition, avoid calling Clear or changing the assigned render target inside an occlusion query begin/end block.

Public Properties

 

IsComplete

Gets a value that indicates whether the occlusion query has completed.

PixelCount

Gets the number of visible pixels.

Public Methods

 

Begin

Begins the application of the query.

End

Ends the application of the query.

PresentationParameters

public class PresentationParameters

Contains presentation parameters.

Public Properties

 

BackBufferFormat

Gets or sets the format of the back buffer.

BackBufferHeight

Gets or sets a value indicating the height of the new swap chain’s back buffer.

BackBufferWidth

Gets or sets a value indicating the width of the new swap chain’s back buffer.

Bounds

Gets the size of this resource.

DepthStencilFormat

Gets or sets the depth-stencil data format.

DeviceWindowHandle

Gets or sets the handle to the device window.

DisplayOrientation

Gets or sets the orientation of the display. The default value is DisplayOrientation.Default, which means orientation is determined automatically from the BackBufferWidth and BackBufferHeight.

IsFullScreen

Gets or sets a value indicating whether the application is in full-screen mode.

MultiSampleCount

Gets or sets a value indicating the number of sample locations during multisampling.

PresentationInterval

Gets or sets the maximum rate at which the swap chain’s back buffers can be presented to the front buffer.

RenderTargetUsage

Gets or sets render target usage flags.

RasterizerState

public class RasterizerState : GraphicsResource

Contains the rasterizer state, which determines how to convert vector data (shapes) into raster data (pixels).

Public Fields

 

CullClockwise

A built-in state object with settings for culling primitives with clockwise winding order.

CullCounterClockwise

A built-in state object with settings for culling primitives with counterclockwise winding order.

CullNone

A built-in state object with settings for not culling any primitives.

Public Properties

 

CullMode

Specifies the conditions for culling or removing triangles. The default value is CullMode.CounterClockwise.

DepthBias

Sets or retrieves the depth bias for polygons, which is the amount of bias to apply to the depth of a primitive to alleviate depth-testing problems for primitives of similar depth. The default value is 0.

FillMode

The fill mode, which defines how a triangle is filled during rendering. The default is FillMode.Solid.

MultiSampleAntiAlias

Enables or disables multisample anti-aliasing. The default is true.

ScissorTestEnable

Enables or disables scissor testing. The default is false.

SlopeScaleDepthBias

Gets or sets a bias value that takes into account the slope of a polygon. This bias value is applied to coplanar primitives to reduce aliasing and other rendering artifacts caused by z-fighting. The default is 0.

RenderTarget2D

public class RenderTarget2D : Texture2D

Contains a 2D texture that can be used as a render target.

Public Properties

 

DepthStencilFormat

Gets the data format for the depth-stencil data.

IsContentLost

Determines whether the index-buffer data has been lost due to a lost-device event.

MultiSampleCount

Gets the number of sample locations during multisampling.

RenderTargetUsage

Gets or sets the render-target usage.

Public Events

 

ContentLost

Occurs when resources are lost due to a lost-device event.

RenderTargetCube

public class RenderTargetCube : TextureCube

Represents a cubic texture resource that will be written to at the end of a render pass.

Public Properties

 

DepthStencilFormat

Gets the depth format of this render target.

IsContentLost

Determines whether the data has been lost due to a lost-device event.

MultiSampleCount

Gets the number of multisample locations.

RenderTargetUsage

Gets the usage mode of this render target.

Public Events

 

ContentLost

Occurs when a resource is lost due to a device being lost.

ResourceCreatedEventArgs

public sealed class ResourceCreatedEventArgs : EventArgs

Contains event data.

Public Properties

 

Resource

The object raising the event.

ResourceDestroyedEventArgs

public sealed class ResourceDestroyedEventArgs : EventArgs

Arguments for a ResourceDestroyed event.

Public Properties

 

Name

Gets the name of the destroyed resource.

Tag

Gets the resource-manager tag of the destroyed resource.

SamplerState

public class SamplerState : GraphicsResource

Contains sampler state, which determines how to sample texture data.

Public Fields

 

AnisotropicClamp

Contains the default state for anisotropic filtering and texture-coordinate clamping.

AnisotropicWrap

Contains the default state for anisotropic filtering and texture-coordinate wrapping.

LinearClamp

Contains the default state for linear filtering and texture-coordinate clamping.

LinearWrap

Contains the default state for linear filtering and texture-coordinate wrapping.

PointClamp

Contains the default state for point filtering and texture-coordinate clamping.

PointWrap

Contains the default state for point filtering and texture-coordinate wrapping.

Public Properties

 

AddressU

Gets or sets the texture-address mode for the u-coordinate.

AddressV

Gets or sets the texture-address mode for the v-coordinate.

AddressW

Gets or sets the texture-address mode for the w-coordinate.

Filter

Gets or sets the type of filtering during sampling.

MaxAnisotropy

Gets or sets the maximum anisotropy. The default value is 0.

MaxMipLevel

Gets or sets the level-of-detail (LOD) index of the largest map to use.

MipMapLevelOf DetailBias

Gets or sets the mipmap LOD bias. The default value is 0.

SamplerStateCollection

public sealed class SamplerStateCollection

Collection of SamplerState objects.

Public Properties

 

Item

Gets a specific SamplerState object using an index value.

SkinnedEffect

public class SkinnedEffect : Effect, IEffectMatrices, IEffectLights, IEffectFog

Contains a configurable effect for rendering skinned character models.

Public Fields

 

MaxBones

The maximum number of bones.

Public Properties

 

Alpha

Gets or sets the material alpha, which determines its transparency. Range is between 1 (fully opaque) and 0 (fully transparent).

AmbientLightColor

Gets or sets the ambient color for a light. The range of color values is from 0 to 1.

DiffuseColor

Gets or sets the diffuse color for a material, the range of color values is from 0 to 1.

DirectionalLight0

Gets the first directional light.

DirectionalLight1

Gets the second directional light.

DirectionalLight2

Gets the third directional light.

EmissiveColor

Gets or sets the emissive color for a material. The range of color values is from 0 to 1.

FogColor

Gets or sets the fog color. The range of color values is from 0 to 1.

FogEnabled

Gets or sets the fog enable flag.

FogEnd

Gets or sets the maximum z value for fog, which ranges from 0 to 1.

FogStart

Gets or sets the minimum z value for fog, which ranges from 0 to 1.

PreferPerPixelLighting

Gets or sets the per-pixel prefer lighting flag.

Projection

Gets or sets the projection matrix.

SpecularColor

Gets or sets the specular color for a material. The range of color values is from 0 to 1.

SpecularPower

Gets or sets the material specular power.

Texture

Gets or sets the current texture.

View

Gets or sets the view matrix.

WeightsPerVertex

Gets or sets the number of per-vertex skinning weights to evaluate, which is either 1, 2, or 4.

World

Gets or sets the world matrix.

Public Methods

 

EnableDefaultLighting

Sets up standard key, fill, and back lighting for a SkinnedEffect.

GetBoneTransforms

Gets the bone-transform matrices for a SkinnedEffect.

SetBoneTransforms

Sets an array of bone transform matrices for a SkinnedEffect.

Protected Methods

 

OnApply

Computes derived parameter values immediately before applying the effect.

Explicit Interface Implementations

 

LightingEnabled

Enables lighting in a SkinnedEffect.

SpriteBatch

public class SpriteBatch : GraphicsResource

Enables a group of sprites to be drawn using the same settings.

Public Methods

 

Begin

Begins a sprite-batch operation.

Draw

Adds a sprite to a batch of sprites to be rendered.

DrawString

Adds a string to a batch of sprites to be rendered.

End

Flushes the sprite batch and restores the device state to how it was before Begin was called.

SpriteFont

public sealed class SpriteFont

Represents a font texture. To load a SpriteFont, click Sprite Font on the Add New Item dialog box. This adds an XML file to your project describing how to build a texture map for your font. At build time, XNA Game Studio creates a texture with the image of the characters of the font you specify, with the specified font point size. At run time, load the font using ContentManager.Load() and pass it to SpriteBatch.DrawString() when drawing text.

Public Properties

 

Characters

Gets a collection of all the characters that are included in the font.

DefaultCharacter

Gets or sets the default character for the font.

LineSpacing

Gets or sets the vertical distance (in pixels) between the base lines of two consecutive lines of text. Line spacing includes the blank space between lines as well as the height of the characters.

Spacing

Gets or sets the spacing of the font characters.

Public Methods

 

MeasureString

Returns the width and height of a string.

Texture

public abstract class Texture : GraphicsResource

Represents a texture resource.

Public Properties

 

Format

Gets the format of the texture data.

LevelCount

Gets the number of texture levels in a multilevel texture.

Texture2D

public class Texture2D : Texture

Represents a 2D grid of texels. A texel represents the smallest unit of a texture that can be read from or written to by the GPU. A texel is composed of one to four components. Specifically, a texel may be any one of the available texture formats represented in the SurfaceFormat enumeration. A Texture2D resource contains a 2D grid of texels. Each texel is addressable by a u, v vector. Because it is a texture resource, it may contain mipmap levels.

Public Properties

 

Bounds

Gets the size of this resource.

Height

Gets the height of this texture resource, in pixels.

Width

Gets the width of this texture resource, in pixels.

Public Methods

 

FromStream

Methods for loading an image.

GetData

Copies texture data into an array.

SaveAsJpeg

Saves texture data as a JPEG.

SaveAsPng

Saves texture data as a PNG.

SetData

Sets data to the texture.

Texture3D

public class Texture3D : Texture

Represents a 3D volume of texels. A texel represents the smallest unit of a texture that can be read from or written to by the GPU. A Texture3D resource (also known as a volume texture) contains a 3D volume of texels. Because it is a texture resource, it may contain mipmap levels.

Public Properties

 

Depth

Gets the depth of this volume texture resource, in pixels.

Height

Gets the height of this texture resource, in pixels.

Width

Gets the width of this texture resource, in pixels.

Public Methods

 

GetData

Gets a copy of the texture data.

SetData

Sets data.

TextureCollection

public sealed class TextureCollection

Represents a collection of Texture objects.

Public Properties

 

Item

Gets or sets the Texture at the specified sampler number.

TextureCube

class definition

Represents a set of six 2D textures, one for each face of a cube. A cube texture is a collection of six textures, one for each face of the cube. All faces must be present in the cube texture. Also, a cube map surface must be the same pixel size in all three dimensions (x, y, and z).

Public Properties

 

Size

Gets the width and height of this texture resource, in pixels.

Public Methods

 

GetData

Returns a copy of the texture data.

SetData

Sets texture data.

VertexBuffer

public class VertexBuffer : GraphicsResource

Represents a list of 3D vertices to be streamed to the graphics device.

Public Properties

 

BufferUsage

Gets the state of the related BufferUsage enumeration.

VertexCount

Gets the number of vertices.

VertexDeclaration

Defines per-vertex data in a buffer.

Public Methods

 

GetData

Returns a copy of the vertex-buffer data.

SetData

Sets the vertex-buffer data.

VertexDeclaration

public class VertexDeclaration : GraphicsResource

A vertex declaration, which defines per-vertex data.

Public Properties

 

VertexStride

The number of bytes from one vertex to the next.

Public Methods

 

GetVertexElements

Gets the vertex-shader declaration.

Interfaces

The following interfaces are found in the Graphics namespace.

IEffectFog

public interface IEffectFog

Gets or sets fog parameters for the current effect.

Public Properties

 

FogColor

Gets or sets the fog color.

FogEnabled

Enables or disables fog.

FogEnd

Gets or sets the fog ending distance.

FogStart

Gets or sets the fog ending distance.

IEffectLights

public interface IEffectLights

Gets or sets lighting parameters for the current effect.

Public Properties

 

AmbientLightColor

Gets or sets the ambient light color for the current effect.

DirectionalLight0

Gets the first directional light for the current effect.

DirectionalLight1

Gets the second directional light for the current effect.

DirectionalLight2

Gets the third directional light for the current effect.

LightingEnabled Property

Enables or disables lighting in an IEffectLights.

Public Methods

 

EnableDefaultLighting

Enables default lighting for the current effect.

IEffectMatrices

public interface IEffectMatrices

Gets or sets transformation-matrix parameters for the current effect.

Public Properties

 

Projection

Gets or sets the projection matrix in the current effect.

View

Gets or sets the view matrix in the current effect.

World

Gets or sets the world matrix in the current effect.

IGraphicsDeviceService

public interface IGraphicsDeviceService

Defines a mechanism for retrieving GraphicsDevice objects.

Public Properties

 

GraphicsDevice

Retrieves a graphics device.

Public Events

 

DeviceCreated

The event that occurs when a graphics device is created.

DeviceDisposing

The event that occurs when a graphics device is disposing.

DeviceReset

The event that occurs when a graphics device is reset.

DeviceResetting

The event that occurs when a graphics device is in the process of resetting.

IVertexType

public interface IVertexType

Vertex type interface, which is implemented by a custom vertex type structure.

Public Properties

 

VertexDeclaration

Vertex declaration, which defines per-vertex data.

Structures

The following structures are found in the Graphics namespace.

ModelBoneCollection.Enumerator

public struct ModelBoneCollection.Enumerator :
    IEnumerator<ModelBone>, IDisposable, IEnumerator

Provides the ability to iterate through the bones in a ModelBoneCollection.

Public Properties

 

Current

Gets the current element in the ModelBoneCollection.

Public Methods

 

MoveNext

Advances the enumerator to the next element of the ModelBoneCollection.

Explicit Interface Implementations

 

System.Collections.IEnumerator.Current

Gets the current element in the ModelBoneCollection as an Object.

System#Collections#IEnumerator#Reset

Sets the enumerator to its initial position, which is before the first element in the ModelBoneCollection.

ModelEffectCollection.Enumerator

public struct ModelEffectCollection.Enumerator :
    IEnumerator<Effect>, IDisposable, IEnumerator

Provides the ability to iterate through the bones in a ModelEffectCollection.

Public Properties

 

Current

Gets the current element in the ModelEffectCollection.

Public Methods

 

MoveNext

Advances the enumerator to the next element of the ModelEffectCollection.

Explicit Interface Implementations

 

System.Collections.IEnumerator.Current

Gets the current element in the ModelEffectCollection as an Object.

System#Collections#IEnumerator#Reset

Sets the enumerator to its initial position, which is before the first element in the ModelEffectCollection.

ModelMeshCollection.Enumerator

public struct ModelMeshCollection.Enumerator : IEnumerator<ModelMesh>, IDisposable, IEnumerator

Provides the ability to iterate through the bones in a ModelMeshCollection.

Public Properties

 

Current

Gets the current element in the ModelMeshCollection.

Public Methods

 

MoveNext

Advances the enumerator to the next element of the ModelMeshCollection.

Explicit Interface Implementations

 

System.Collections.IEnumerator.Current

Gets the current element in the ModelMeshCollection as an Object.

System#Collections#IEnumerator#Reset

Sets the enumerator to its initial position, which is before the first element in the ModelMeshCollection.

ModelMeshPartCollection.Enumerator

public struct ModelMeshPartCollection.Enumerator : IEnumerator<ModelMeshPart>, IDisposable, IEnumerator

Provides the ability to iterate through the bones in a ModelMeshPartCollection.

Public Properties

 

Current

Gets the current element in the ModelMeshPartCollection.

Public Methods

 

MoveNext

Advances the enumerator to the next element of the ModelMeshPartCollection.

Explicit Interface Implementations

 

System.Collections.IEnumerator.Current

Gets the current element in the ModelMeshPartCollection as an Object.

System#Collections#IEnumerator#Reset

Sets the enumerator to its initial position, which is before the first element in the ModelMeshPartCollection.

RenderTargetBinding

public struct RenderTargetBinding

Binds an array of render targets.

Public Properties

 

CubeMapFace

Gets one face of a cube map.

RenderTarget

Gets a 2D texture.

VertexBufferBinding

public struct VertexBufferBinding

Binding structure that specifies a vertex buffer and other per-vertex parameters (such as offset and instancing) for a graphics device.

Public Properties

 

InstanceFrequency

Gets the instancing frequency.

VertexBuffer

Gets a vertex buffer.

VertexOffset

Gets the offset between the beginning of the buffer and the vertex data to use.

VertexElement

public struct VertexElement

Defines input vertex data to the pipeline.

Public Properties

 

Offset

Retrieves or sets the offset (if any) from the beginning of the stream to the beginning of the vertex data.

UsageIndex

Modifies the usage data to allow the user to specify multiple usage types.

VertexElementFormat

Gets or sets the format of this vertex element.

VertexElementUsage

Gets or sets a value describing how the vertex element is to be used.

VertexPositionColor

public struct VertexPositionColor : IVertexType

Describes a custom vertex-format structure that contains position and color information.

Public Fields

 

Color

The vertex color.

Position

The XYZ position.

VertexDeclaration

Vertex declaration, which defines per-vertex data.

Explicit Interface Implementations

 

Microsoft.Xna.Framework.Graphics.IVertexType.VertexDeclaration

Gets a vertex declaration.

VertexPositionColorTexture

public struct VertexPositionColorTexture : IVertexType

Describes a custom vertex-format structure that contains position information, color information, and one set of texture coordinates.

Public Fields

 

Color

The vertex color.

Position

The XYZ position.

TextureCoordinate

UV texture coordinates.

VertexDeclaration

Vertex declaration, which defines per-vertex data.

Explicit Interface Implementations

 

Microsoft.Xna.Framework.Graphics.IVertexType.VertexDeclaration

Gets a vertex declaration.

VertexPositionNormalTexture

public struct VertexPositionNormalTexture : IVertexType

Describes a custom vertex-format structure that contains position, normal data, and one set of texture coordinates.

Public Fields

 

Normal

The XYZ surface normal.

Position

The XYZ position.

TextureCoordinate

UV texture coordinates.

VertexDeclaration

Vertex declaration, which defines per-vertex data.

Explicit Interface Implementations

 

Microsoft.Xna.Framework.Graphics.IVertexType.VertexDeclaration

Gets a vertex declaration.

VertexPositionTexture

public struct VertexPositionTexture : IVertexType

Describes a custom vertex-format structure that contains position information and one set of texture coordinates.

Public Fields

 

Position

The XYZ position.

TextureCoordinate

UV texture coordinates.

VertexDeclaration

Vertex declaration, which defines per-vertex data.

Explicit Interface Implementations

 

Microsoft.Xna.Framework.Graphics.IVertexType.VertexDeclaration

Gets a vertex declaration.

Viewport

public struct Viewport

Defines the window dimensions of a render-target surface onto which a 3D volume projects.

Public Properties

 

AspectRatio

Gets the aspect ratio used by the viewport.

Bounds

Gets the size of this resource.

Height

Gets or sets the height dimension of the viewport on the render-target surface, in pixels.

MaxDepth

Gets or sets the maximum depth of the clip volume.

MinDepth

Gets or sets the minimum depth of the clip volume.

TitleSafeArea

Returns the title-safe area of the current viewport.

Width

Gets or sets the width dimension of the viewport on the render-target surface, in pixels.

X

Gets or sets the X pixel coordinate value of the upper-left corner of the viewport on the render-target surface.

Y

Gets or sets the Y pixel coordinate value of the upper-left corner of the viewport on the render-target surface.

Public Methods

 

Project

Projects a 3D vector from object space into screen space.

Unproject

Converts a screen-space point into a corresponding point in world space.

Enumerations

Following are the enumerations in the Graphics namespace.

Blend

public enum Blend

Defines color-blending factors.

Zero

Each component of the color is multiplied by (0, 0, 0, 0).

One

Each component of the color is multiplied by (1, 1, 1, 1).

SourceColor

Each component of the color is multiplied by the source color. This can be represented as (Rs, Gs, Bs, As), where R, G, B, and A stand for the red, green, blue, and alpha source values, respectively.

InverseSourceColor

Each component of the color is multiplied by the inverse of the source color. This can be represented as (1 — Rs, 1 — Gs, 1 — Bs, 1 — As) where R, G, B, and A stand for the red, green, blue, and alpha destination values, respectively.

SourceAlpha

Each component of the color is multiplied by the alpha value of the source. This can be represented as (As, As, As, As), where As is the alpha source value.

InverseSourceAlpha

Each component of the color is multiplied by the inverse of the alpha value of the source. This can be represented as (1 — As, 1 — As, 1 — As, 1 — As), where As is the alpha destination value.

DestinationAlpha

Each component of the color is multiplied by the alpha value of the destination. This can be represented as (Ad, Ad, Ad, Ad), where Ad is the destination alpha value.

InverseDestinationAlpha

Each component of the color is multiplied by the inverse of the alpha value of the destination. This can be represented as (1 — Ad, 1 — Ad, 1 — Ad, 1 — Ad), where Ad is the alpha destination value.

DestinationColor

Each component color is multiplied by the destination color. This can be represented as (Rd, Gd, Bd, Ad), where R, G, B, and A stand for red, green, blue, and alpha destination values, respectively.

InverseDestinationColor

Each component of the color is multiplied by the inverse of the destination color. This can be represented as (1 — Rd, 1 — Gd, 1 — Bd, 1 — Ad), where Rd, Gd, Bd, and Ad stand for the red, green, blue, and alpha destination values, respectively.

SourceAlphaSaturation

Each component of the color is multiplied by either the alpha of the source color or the inverse of the alpha of the source color, whichever is greater. This can be represented as (f, f, f, 1), where f = min(A, 1 — Ad).

BlendFactor

Each component of the color is multiplied by a constant set in BlendFactor.

InverseBlendFactor

Each component of the color is multiplied by the inverse of a constant set in BlendFactor.

BlendFunction

public enum BlendFunction

Defines how to combine a source color with the destination color already on the render target for color blending.

Add

The result is the destination added to the source.Result = (Source Color * Source Blend) + (Destination Color * Destination Blend)

Max

The result is the maximum of the source and destination.Result = max( (Source Color * Source Blend), (Destination Color * Destination Blend) )

Min

The result is the minimum of the source and destination.Result = min( (Source Color * Source Blend), (Destination Color * Destination Blend) )

ReverseSubtract

The result is the source subtracted from the destination.Result = (Destination Color * Destination Blend) — (Source Color * Source Blend)

Subtract

The result is the destination subtracted from the source.Result = (Source Color * Source Blend) — (Destination Color * Destination Blend)

BufferUsage

public enum BufferUsage

Specifies special usage of the buffer contents.

None

None

WriteOnly

Indicates that the application only writes to the vertex buffer. If specified, the driver chooses the best memory location for efficient writing and rendering. Attempts to read from a write-only vertex buffer fail.

ClearOptions

public enum ClearOptions

Specifies the buffer to use when calling Clear.

DepthBuffer

A depth buffer.

Stencil

A stencil buffer.

Target

A render target.

ColorWriteChannels

public enum ColorWriteChannels

Defines the color channels that can be chosen for a per-channel write to a render-target color buffer.

All

All buffer channels.

Alpha

Alpha channel of a buffer.

Blue

Blue channel of a buffer.

Green

Green channel of a buffer.

None

No channel selected.

Red

Red channel of a buffer.

CompareFunction

public enum CompareFunction

Defines comparison functions that can be chosen for alpha, stencil, or depth-buffer tests.

Always

Always pass the test.

Equal

Accept the new pixel if its value is equal to the value of the current pixel.

Greater

Accept the new pixel if its value is greater than the value of the current pixel.

GreaterEqual

Accept the new pixel if its value is greater than or equal to the value of the current pixel.

Less

Accept the new pixel if its value is less than the value of the current pixel.

LessEqual

Accept the new pixel if its value is less than or equal to the value of the current pixel.

Never

Always fail the test.

NotEqual

Accept the new pixel if its value does not equal the value of the current pixel.

CubeMapFace

public enum CubeMapFace

Defines the faces of a cube map in the TextureCube class type.

NegativeX

Negative x-face of the cube map.

NegativeY

Negative y-face of the cube map.

NegativeZ

Negative z-face of the cube map.

PositiveX

Positive x-face of the cube map.

PositiveY

Positive y-face of the cube map.

PositiveZ

Positive z-face of the cube map.

CullMode

public enum CullMode

Defines winding orders that may be used to identify back faces for culling.

CullClockwiseFace

Cull back faces with clockwise vertices.

CullCounterClockwiseFace

Cull back faces with counterclockwise vertices.

None

Do not cull back faces.

DepthFormat

public enum DepthFormat

Defines the format of data in a depth-stencil buffer. A depth buffer contains depth data and possibly stencil data. Control a depth buffer using a state object.

Depth16

A buffer that contains 16 bits of depth data.

Depth24

A buffer that contains 24 bits of depth data.

Depth24Stencil8

A 32-bit buffer that contains 24 bits of depth data and 8 bits of stencil data.

None

Do not create a depth buffer.

EffectParameterClass

public enum EffectParameterClass

Defines classes that can be used for effect parameters or shader constants.

Matrix

The constant is a matrix.

Object

The constant is either a texture, a shader, or a string.

Scalar

The constant is a scalar.

Struct

The constant is a structure.

Vector

The constant is a vector.

EffectParameterType

public enum EffectParameterType

Defines types that can be used for effect parameters or shader constants.

Bool

Parameter is a Boolean. Any non-zero value passed in will be mapped to 1 (true) before being written into the constant table; otherwise, the value will be set to 0 in the constant table.

Int32

Parameter is an integer. Any floating-point values passed in will be rounded off (to zero decimal places) before being written into the constant table.

Single

Parameter is a floating-point number.

String

Parameter is a string.

Texture

Parameter is a texture.

Texture1D

Parameter is a 1D texture.

Texture2D

Parameter is a 2D texture.

Texture3D

Parameter is a 3D texture.

TextureCube

Parameter is a cube texture.

Void

Parameter is a void pointer.

FillMode

public enum FillMode

Describes options for filling the vertices and lines that define a primitive.

Solid

Draw solid faces for each primitive.

WireFrame

Draw lines connecting the vertices that define a primitive face.

GraphicsDeviceStatus

public enum GraphicsDeviceStatus

Describes the status of the device.

Lost

The device has been lost.

Normal

The device is normal.

NotReset

The device has not been reset.

GraphicsProfile

public enum GraphicsProfile

Identifies the set of supported devices for the game based on device capabilities.

HiDef

Use the largest available set of graphic features and capabilities to target devices, such as an Xbox 360 console and a Windows-based computer, that have more enhanced graphic capabilities.

Reach

Use a limited set of graphic features and capabilities, allowing the game to support the widest variety of devices, including all Windows-based computers and Windows Phones.

IndexElementSize

public enum IndexElementSize

Defines the size of an element of an index buffer.

SixteenBits

16 bits.

ThirtyTwoBits

32 bits.

PresentInterval

public enum PresentInterval

Defines flags that describe the relationship between the adapter refresh rate and the rate at which Present operations are completed.

Default

Equivalent to setting One.

One

The driver waits for the vertical retrace period. Present operations are not affected more frequently than the screen-refresh rate; the runtime completes one Present operation per adapter refresh period, at most. This option is always available for both windowed and full-screen swap chains.

Two

The driver waits for the vertical retrace period. Present operations are not affected more frequently than every second screen refresh.

Immediate

The runtime updates the window client area immediately, and might do so more than once during the adapter refresh period. Present operations might be affected immediately. This option is always available for both windowed and full-screen swap chains.

PrimitiveType

public enum PrimitiveType

Defines how vertex data is ordered.

TriangleList

The data is ordered as a sequence of triangles; each triangle is described by three new vertices. Back-face culling is affected by the current winding-order render state.

TriangleStrip

The data is ordered as a sequence of triangles; each triangle is described by two new vertices and one vertex from the previous triangle. The back-face culling flag is flipped automatically on even-numbered triangles.

LineList

The data is ordered as a sequence of line segments; each line segment is described by two new vertices. The count may be any positive integer.

LineStrip

The data is ordered as a sequence of line segments; each line segment is described by one new vertex and the last vertex from the previous line seqment. The count may be any positive integer.

RenderTargetUsage

public enum RenderTargetUsage

Determines how render target data is used once a new render target is set.

DiscardContents

Always clears the render target data.

PlatformContents

Either clears or keeps the data, depending on the current platform. On Xbox 360, the render target will discard contents. On a PC, the render target will discard if multisampling is enabled, and preserve the contents if not.

PreserveContents

Always keeps the render-target data.

SetDataOptions

public enum SetDataOptions

Describes whether existing vertex or index-buffer data will be overwritten or discarded during a SetData operation.

Discard

The SetData operation will discard the entire buffer. A pointer to a new memory area is returned so that the direct memory access (DMA) and rendering from the previous area do not stall.

None

Portions of existing data in the buffer may be overwritten during this operation.

NoOverwrite

The SetData operation will not overwrite existing data in the vertex and index buffers. Specifying this option allows the driver to return immediately from a SetData operation and continue rendering.

SpriteEffects

public enum SpriteEffects

Defines sprite-mirroring options.

FlipHorizontally

Rotate 180 degrees about the Y axis before rendering.

FlipVertically

Rotate 180 degrees about the X axis before rendering.

None

No rotations specified.

SpriteSortMode

public enum SpriteSortMode

Defines sprite sort-rendering options.

BackToFront

Same as Deferred mode, except sprites are sorted by depth in back-to-front order prior to drawing. This procedure is recommended when drawing transparent sprites of varying depths.

Deferred

Sprites are not drawn until End is called. End will apply graphics-device settings and draw all the sprites in one batch, in the same order calls to Draw were received. This mode allows Draw calls to two or more instances of SpriteBatch without introducing conflicting graphics-device settings. SpriteBatch defaults to Deferred mode.

FrontToBack

Same as Deferred mode, except sprites are sorted by depth in front-to-back order prior to drawing. This procedure is recommended when drawing opaque sprites of varying depths.

Immediate

Begin will apply new graphics-device settings, and sprites will be drawn within each Draw call. In Immediate mode, there can only be one active SpriteBatch instance without introducing conflicting device settings.

Texture

Same as Deferred mode, except sprites are sorted by texture prior to drawing. This can improve performance when drawing non-overlapping sprites of uniform depth.

StencilOperation

public enum StencilOperation

Defines stencil-buffer operations.

Decrement

Decrements the stencil-buffer entry, wrapping to the maximum value if the new value is less than 0.

DecrementSaturation

Decrements the stencil-buffer entry, clamping to 0.

Increment

Increments the stencil-buffer entry, wrapping to 0 if the new value exceeds the maximum value.

IncrementSaturation

Increments the stencil-buffer entry, clamping to the maximum value.

Invert

Inverts the bits in the stencil-buffer entry.

Keep

Does not update the stencil-buffer entry. This is the default value.

Replace

Replaces the stencil-buffer entry with a reference value.

Zero

Sets the stencil-buffer entry to 0.

SurfaceFormat

public enum SurfaceFormat

Defines various types of surface formats. Two-dimensional (2D) images are represented by a range of memory called a surface. Within a surface, each element holds a color value representing a small section of the image, called a pixel. An image’s detail level is defined by the number of pixels needed to represent the image and the number of bits needed for the image’s color spectrum. For example, an image that is 800 pixels wide by 600 pixels high with 32 bits of color for each pixel (written as 800 × 600 × 32) is more detailed than an image that is 640 pixels wide by 480 pixels tall with 16 bits of color for each pixel (written as 640 × 480 × 16). Likewise, the more-detailed image requires a larger surface to store the data. For an 800 × 600 × 32 image, the surface’s array dimensions are 800 × 600, and each element holds a 32-bit value to represent its color.

All formats are listed from left to right, most-significant bit to least-significant bit. For example, ARGB formats are ordered from the most-significant bit channel A (alpha) to the least-significant bit channel B (blue). When traversing surface data, the data is stored in memory from least-significant bit to most-significant bit, which means the channel order in memory is from least-significant bit (blue) to most-significant bit (alpha).

The default value for formats that contain undefined channels (Rg32, Alpha8, and so on) is 1. The only exception is the Alpha8 format, which is initialized to 000 for the three color channels.

Color

(Unsigned format) 32-bit ARGB pixel format with alpha, using 8 bits per channel.

Bgr565

(Unsigned format) 16-bit BGR pixel format with 5 bits for blue, 6 bits for green, and 5 bits for red.

Bgra5551

(Unsigned format) 16-bit BGRA pixel format where 5 bits are reserved for each color and 1 bit is reserved for alpha.

Bgra4444

(Unsigned format) 16-bit BGRA pixel format with 4 bits for each channel.

Dxt1

DXT1 compression texture format. The runtime will not allow an application to create a surface using a DXTn format unless the surface dimensions are multiples of 4. This applies to off-screen–plain surfaces, render targets, 2D textures, cube textures, and volume textures.

Dxt3

DXT3 compression texture format. The runtime will not allow an application to create a surface using a DXTn format unless the surface dimensions are multiples of 4. This applies to offscreen-plain surfaces, render targets, 2D textures, cube textures, and volume textures.

Dxt5

DXT5 compression texture format. The runtime will not allow an application to create a surface using a DXTn format unless the surface dimensions are multiples of 4. This applies to offscreen-plain surfaces, render targets, 2D textures, cube textures, and volume textures.

NormalizedByte2

(Signed format) 16-bit bump-map format using 8 bits each for U and V data.

NormalizedByte4

(Signed format) 32-bit bump-map format using 8 bits for each channel.

Rgba1010102

(Unsigned format) 32-bit RGBA pixel format using 10 bits for each color and 2 bits for alpha.

Rg32

(Unsigned format) 32-bit pixel format using 16 bits each for red and green.

Rgba64

(Unsigned format) 64-bit RGBA pixel format using 16 bits for each component.

Alpha8

(Unsigned format) 8-bit alpha only.

Single

(IEEE format) 32-bit float format using 32 bits for the red channel.

Vector2

(IEEE format) 64-bit float format using 32 bits for the red channel and 32 bits for the green channel.

Vector4

(IEEE format) 128-bit float format using 32 bits for each channel (alpha, blue, green, red).

HalfSingle

(Floating-point format) 16-bit float format using 16 bits for the red channel.

HalfVector2

(Floating-point format) 32-bit float format using 16 bits for the red channel and 16 bits for the green channel.

HalfVector4

(Floating-point format) 64-bit float format using 16 bits for each channel (alpha, blue, green, red).

HdrBlendable

(Floating-point format) For high dynamic range data.

TextureAddressMode

public enum TextureAddressMode

Defines modes for addressing texels using texture coordinates that are outside the typical range of 0.0 to 1.0.

Clamp

Texture coordinates outside the range [0.0, 1.0] are set to the texture color at 0.0 or 1.0, respectively.

Mirror

Similar to Wrap, except that the texture is flipped at every integer junction. For U values between 0 and 1, for example, the texture is addressed normally; between 1 and 2, the texture is flipped (mirrored); between 2 and 3, the texture is normal again, and so on.

Wrap

Tile the texture at every integer junction. For example, for U values between 0 and 3, the texture is repeated three times; no mirroring is performed.

TextureFilter

public enum TextureFilter

Defines filtering types during texture sampling. A texture coordinate determines where to sample a texture. When a texel does not map exactly to one pixel, filtering is necessary to magnify (enlarge) or minify (shrink) the texture.

Not all valid filtering modes for a device apply to volume maps. In general, Point and Linear magnification filters are supported for volume maps. Devices that support anisotropic filtering for 2D maps do not necessarily support it for volume maps. However, applications that enable anisotropic filtering, even if they do not support it, receive the best available filtering (probably linear).

Linear

Use linear filtering.

Point

Use point filtering.

Anisotropic

Use anisotropic filtering.

LinearMipPoint

Use linear filtering to shrink (minify) or expand (magnify), and point filtering between mipmap levels (mip).

PointMipLinear

Use point filtering to shrink (minify) or expand (magnify), and linear filtering between mipmap levels.

MinLinearMagPoint MipLinear

Use linear filtering to shrink (minify), point filtering to expand (magnify), and linear filtering between mipmap levels.

MinLinearMagPointMipPoint

Use linear filtering to shrink (minify), point filtering to expand (magnify), and point filtering between mipmap levels.

MinPointMagLinearMipLinear

Use point filtering to shrink (minify), linear filtering to expand (magnify), and linear filtering between mipmap levels.

MinPointMagLinearMipPoint

Use point filtering to shrink (minify), linear filtering to expand (magnify), and point filtering between mipmap levels.

VertexElementFormat

public enum VertexElementFormat

Defines vertex element formats.

Single

Single-component, 32-bit floating-point, expanded to (float, 0, 0, 1).

Vector2

Two-component, 32-bit floating-point, expanded to (float, Float32 value, 0, 1).

Vector3

Three-component, 32-bit floating point, expanded to (float, float, float, 1).

Vector4

Four-component, 32-bit floating point, expanded to (float, float, float, float).

HalfVector2

Two-component, 16-bit floating point expanded to (value, value, value, value). This type is valid for vertex shader version 2.0 or higher.

HalfVector4

Four-component, 16-bit floating-point expanded to (value, value, value, value). This type is valid for vertex shader version 2.0 or higher.

Color

Four-component, packed, unsigned byte, mapped to 0 to 1 range. Input is in Int32 format (ARGB) expanded to (R, G, B, A).

NormalizedShort2

Normalized, two-component, signed short, expanded to (first short/32767.0, second short/32767.0, 0, 1). This type is valid for vertex shader version 2.0 or higher.

NormalizedShort4

Normalized, four-component, signed short, expanded to (first short/32767.0, second short/32767.0, third short/32767.0, fourth short/32767.0). This type is valid for vertex shader version 2.0 or higher.

Short2

Two-component, signed short expanded to (value, value, 0, 1).

Short4

Four-component, signed short expanded to (value, value, value, value).

Byte4

Four-component, unsigned byte.

VertexElementUsage

public enum VertexElementUsage

Defines usage for vertex elements.

Binormal

Vertex binormal data.

BlendIndices

Blending indices data. (BlendIndices with UsageIndex = 0) specifies matrix indices for fixed-function vertex processing using indexed paletted skinning.

BlendWeight

Blending weight data. (BlendWeight with UsageIndex = 0) specifies the blend weights in fixed-function vertex processing.

Color

Vertex data contains diffuse or specular color. (Color with UsageIndex = 0) specifies the diffuse color in the fixed-function vertex shader and in pixel shaders prior to ps_3_0. (Color with UsageIndex = 1) specifies the specular color in the fixed-function vertex shader and in pixel shaders prior to ps_3_0.

Depth

Vertex data contains depth data.

Fog

Vertex data contains fog data. (Fog with UsageIndex = 0) specifies a fog blend value to use after pixel shading is finished. This flag applies to pixel shaders prior to version ps_3_0.

Normal

Vertex normal data. (Normal with UsageIndex = 0) specifies vertex normals for fixed-function vertex processing and the N-patch tessellator. (Normal with UsageIndex = 1) specifies vertex normals for fixed-function vertex processing for skinning.

PointSize

Point size data. (PointSize with UsageIndex = 0) specifies the point-size attribute used by the setup engine of the rasterizer to expand a point into a quad for the point-sprite functionality.

Position

Position data. (Position with UsageIndex = 0) specifies the non-transformed position in fixed-function vertex processing and the N-patch tessellator. (Position with UsageIndex = 1) specifies the non-transformed position in the fixed-function vertex shader for skinning.

Sample

Vertex data contains sampler data. (Sample with UsageIndex = 0) specifies the displacement value to look up.

Tangent

Vertex tangent data.

TessellateFactor

Single, positive floating-point value. (TessellateFactor with UsageIndex = 0) specifies a tessellation factor used in the tessellation unit to control the rate of tessellation.

TextureCoordinate

Texture-coordinate data. (TextureCoordinate, n) specifies texture coordinates in fixed-function vertex processing and in pixel shaders prior to ps_3_0. These coordinates can be used to pass user-defined data.

Hint

There is no Graphics demo project in this chapter because we cover rendering in the whole later in this book.

Summary

This chapter was wholly devoted to the Graphics namespace, which is quite large and extensive, but only because it is jam packed with features. You may refer back to this chapter at any time when working on the rendering projects later in this book.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.218.127.141