Effect.Begin(FX) Method (Microsoft.DirectX.Direct3D)

  • Article

How Do I...?

  • Using an Effect

Begins the application of an effect technique.

Definition

Visual Basic Public Function Begin( _
    ByVal flags As FX _
) As Integer
C# public int Begin(
    FX flags
);
C++ public:
int Begin(
    FX flags
);
JScript public function Begin(
    flags : FX
) : int;

Parameters

flags Microsoft.DirectX.Direct3D.FX
One or more FX enumerated values that determine whether state modified by an effect will be saved and restored. The default value, 0, specifies that Effect.Begin and Effect.End will save and restore all state modified by the effect (including pixel and vertex shader constants). DoNotSaveShaderState indicates that shader device state will not be saved or restored; DoNotSaveState indicates that device state will not be saved or restored.

Return Value

System.Int32
An integer value that indicates the number of passes needed to render the current effect technique.

Remarks

This method returns the number of passes needed to render the current effect technique. The application must incrementally call Effect.BeginPass for each pass before drawing the geometry to which the effect needs to be applied, followed by a call to Effect.EndPass. After all passes are rendered, Effect.End must be called.

Exceptions

InvalidCallException

The method call is invalid. For example, a method's parameter might contain an invalid value.

InvalidDataException

The data is invalid.

How Do I...?

Using an Effect

This example demonstrates how to use an effect technique that was loaded from a file.

Add effects code to your rendering method, such as OnRender(), in-between calls to Device.BeginScene and Device.EndScene.

  1. Create or obtain access to a high-level shader language (HLSL) file (.fx).
  2. Load the HLSL file using Effect.FromFile.
  3. Set Effect.Technique with the effect's technique.
  4. Use Effect.Begin to obtain the number of passes for the effect.
  5. Create a loop to iterate through all of the effect's passes. Rendering an effect occurs within a loop between calls to Effect.BeginPass and Effect.EndPass. The loop itself is nested between calls to Effect.Begin and Effect.End.
  6. Render each pass within the loop with calls to Effect.BeginPass, Device.DrawPrimitives, and Effect.EndPass.

In the following C# code example, device is assumed to be the rendering Device.

              [C#]
              

public void OnRender ()
{
    .
    .
    .

    // Load the effect from file.
    Effect effect = Effect.FromFile(device, "shadercode.fx", null,
                                    ShaderFlags.None, null);
    // Set the technique.
    effect.Technique = "ShaderTechnique";

    // Note: Effect.Begin returns the number of
    // passes required to render the effect.
    int passes = effect.Begin(0);
    
    // Loop through all of the effect's passes.
    for (int i = 0; i < passes; i++)
    {
        // Set a shader constant
        effect.SetValue("WorldMatrix", worldMatrix);

        // Set state for the current effect pass.
        effect.BeginPass(i);
        
        // Render some primitives.
        device.DrawPrimitives(PrimitiveType.TriangleList, 0, 1);
        
        // End the effect pass
        effect.EndPass();
    }

    // Must call Effect.End to signal the end of the technique.
    effect.End();

    .
    .
    .
}