IDCompositionAnimation

1つ以上の Microsoft DirectComposition オブジェクトの、1つ以上のプロパティをアニメーションさせるための関数を表します。

アニメーション関数をリセットし、セグメントを含まない状態にします。

関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、DirectComposition Error Codes を参照してください。

このメソッドは、アニメーション関数を、アニメーションが最初に構築されたときと同じクリーンな状態に戻します。このメソッドを呼び出した後は、次に追加されるセグメントがアニメーション関数の最初のセグメントになります。最初のセグメントであるため、非負の任意の開始オフセットを指定できます。

アニメーション関数が開始する絶対時刻を設定します。

型: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、DirectComposition Error Codes を参照してください。

既定では、アニメーション関数はアニメーションの最初のフレームが有効になった時点で開始します。たとえば、アプリケーションがオフセット 0 に単一のプリミティブを持つ単純なアニメーション関数を作成し、それを何らかのプロパティに関連付けてから IDCompositionDevice::Commit メソッドを呼び出した場合、そのコミットを含む最初のフレームでは、最初のプリミティブについてオフセット 0 でアニメーションがサンプリングされます。

つまり、すべてのアニメーションの実際の既定の開始時刻は、アプリケーションがアニメーションを作成してから Commit を呼び出すまでの時間や、合成エンジンがコミットされた変更を取り込むまでにかかる時間によって変動します。アプリケーションは SetAbsoluteBeginTime メソッドを使用して、アニメーションの開始時刻をより細かく制御できます。

このメソッドは、アニメーションがいつ有効になるかを制御するものではありません。開始後にアニメーションがどのようにサンプリングされるかにのみ影響します。アプリケーションが次のフレームの時刻をそのまま絶対開始時刻として指定した場合、結果はこのメソッドを呼び出さなかった場合と同じになります。指定した開始時刻が次のフレームの時刻と異なる場合、結果は次のいずれかになります。

• 指定した時刻が次のフレームの時刻より後の場合、アニメーションの開始は指定した開始時刻まで遅延されます。
• 指定した時刻が次のフレームの時刻より前の場合、アニメーションの先頭部分は破棄され、アニメーション関数の途中からサンプリングが開始されます。

3次多項式セグメントをアニメーション関数に追加します。

型: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、DirectComposition Error Codes を参照してください。

3次セグメントは、3次多項式に従って時間を値へ変換します。時間の入力 (t) に対する出力値は、次の式で与えられます。

x(t) = at³ + bt² + ct + d

いずれかのパラメーターが NaN、正の無限大、負の無限大である場合、このメソッドは失敗します。

アニメーションセグメントは昇順に追加する必要があるため、beginOffset パラメーターが直前のセグメント (存在する場合) の beginOffset パラメーター以下である場合、このメソッドは失敗します。

このアニメーションセグメントは、アニメーション関数内の次のセグメントの開始時刻まで有効です。アニメーション関数にそれ以上セグメントがない場合、このセグメントは無期限に有効なままとなります。

constantCoefficient 以外のすべての係数が 0 の場合、このセグメントの値は時間が経過しても一定であり、セグメントの間はアニメーションによる再合成は発生しません。

例

次の例では、2つの3次多項式セグメントを持つアニメーション関数を作成します。

HRESULT DoAnimatedRotation(IDCompositionDevice *pDevice,
                           IDCompositionRotateTransform *pRotateTransform,
                           IDCompositionVisual *pVisual, 
                           float animationTime) 
{
    HRESULT hr = S_OK;
    IDCompositionAnimation *pAnimation = nullptr;

    // Create an animation object. 
    hr = pDevice->CreateAnimation(&pAnimation);

    if (SUCCEEDED(hr)) 
    {
        // Create the animation function by adding cubic polynomial segments.
        // For a given time input (t), the output value is
        // a*t^3 + b* t^2 + c*t + d.
        // 
        // The following segment will rotate the visual clockwise.
        pAnimation->AddCubic(
            0.0,                                // Begin offset
            0.0,                                // Constant coefficient - d
            (360.0f * 1.0f) / animationTime,    // Linear coefficient - c
            0.0,                                // Quadratic coefficient - b
            0.0);                               // Cubic coefficient - a

        // The following segment will rotate the visual counterclockwise.
        pAnimation->AddCubic(
            animationTime,
            0.0,
            -(360.0f * 1.0f) / animationTime,
            0.0,
            0.0);

        // Set the end of the animation.
        pAnimation->End(
            2 * animationTime,  // End offset
            0.0);               // End value

        // Apply the animation to the Angle property of the
        // rotate transform. 
        hr = pRotateTransform->SetAngle(pAnimation);
    }

    if (SUCCEEDED(hr))
    {
        // Apply the rotate transform object to a visual.
        hr = pVisual->SetTransform(pRotateTransform);
    }

    if (SUCCEEDED(hr))
    {
        // Commit the changes to the composition.
        hr = pDevice->Commit();
    }

    SafeRelease(&pAnimation);

    return hr;
}

正弦波セグメントをアニメーション関数に追加します。

型: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、DirectComposition Error Codes を参照してください。

いずれかのパラメーターが NaN、正の無限大、負の無限大である場合、または beginOffset パラメーターが負の値である場合、このメソッドは失敗します。

アニメーションセグメントは昇順に追加する必要があるため、beginOffset パラメーターが直前のセグメント (存在する場合) の beginOffset パラメーター以下である場合、このメソッドは失敗します。

このアニメーションセグメントは、アニメーション関数内の次のセグメントの開始時刻まで有効です。アニメーション関数にそれ以上セグメントがない場合、このセグメントは無期限に有効なままとなります。

アニメーション関数の指定した部分を繰り返す、リピートセグメントを追加します。

型: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、DirectComposition Error Codes を参照してください。

いずれかのパラメーターが NaN、正の無限大、負の無限大である場合、このメソッドは失敗します。

アニメーションセグメントは昇順に追加する必要があるため、beginOffset パラメーターが直前のセグメントの beginOffset パラメーター以下である場合、このメソッドは失敗します。また、これがアニメーション関数に追加される最初のセグメントである場合も失敗します。

このアニメーションセグメントは、次のセグメントの開始時刻まで有効です。アニメーション関数にそれ以上セグメントがない場合、このセグメントは無期限に有効なままとなります。

例

次の例では、リピートセグメントを含むアニメーション関数を作成し、そのアニメーションをスケール変換の x 軸と y 軸に適用します。

HRESULT MyCreateAnimatedScaleTransform(IDCompositionDevice *pDevice, 
                                       IDCompositionVisual *pVisual)
{
    HRESULT hr = S_OK;
    IDCompositionAnimation *pAnimation = nullptr;
    IDCompositionScaleTransform *pScaleTransform = nullptr;

    // Validate the pointers.
    if (pDevice == nullptr || pVisual == nullptr)
        return E_INVALIDARG;
    
    // Create an animation object.
    hr = pDevice->CreateAnimation(&pAnimation);
    if (SUCCEEDED(hr))
    {
        // Add segments to the animation function.
        pAnimation->AddCubic(0, 1, -0.5, 0, 0);
        pAnimation->AddRepeat(3.0, 3.0);
        pAnimation->End(10, .5);

        // Create a scale transform object.
          hr = pDevice->CreateScaleTransform(&pScaleTransform);
    }

    if (SUCCEEDED(hr))
    {
        // Apply the animation to the x and y axes of the scale transform.
        pScaleTransform->SetScaleX(pAnimation);
        pScaleTransform->SetScaleY(pAnimation);

        // Apply the scale transform to the visual.
        hr = pVisual->SetTransform(pScaleTransform);
    }

    if (SUCCEEDED(hr))
    {
        // Commit the composition for rendering.
        hr = pDevice->Commit();
    }

    // Clean up.
    SafeRelease(&pAnimation);
    SafeRelease(&pScaleTransform);

    return hr;
}

アニメーション関数の終了を示す終了セグメントを追加します。

型: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、DirectComposition Error Codes を参照してください。

指定したオフセットに達すると、このアニメーションの影響を受けるプロパティは指定した最終値に設定され、その後アニメーションは停止します。終了セグメントを追加しない場合、アニメーション関数の最後のセグメントが無期限に実行されます。このメソッドの呼び出しは、アニメーション関数の最後のセグメントとして、3次・2次・1次の係数がすべて 0 で、定数係数が目的の最終値である3次多項式を指定することと意味的に同じです。

アニメーションセグメントは昇順に追加する必要があるため、endOffset パラメーターが直前のセグメントの beginOffset パラメーター以下である場合、このメソッドは失敗します。また、これがアニメーション関数に追加される最初のセグメントである場合も失敗します。

このメソッドを呼び出した後は、IDCompositionAnimation::Reset メソッドを除き、このアニメーションオブジェクトのすべてのメソッドが失敗します。