ID2D1RenderTarget::BeginDraw-Methode (d2d1.h)

Initiiert das Zeichnen für dieses Renderziel.

Syntax

void BeginDraw();

Rückgabewert

Keine

Bemerkungen

Zeichnungsvorgänge können nur zwischen einem BeginDraw - und EndDraw-Aufruf ausgegeben werden.

BeginDraw und EndDraw werden verwendet, um anzugeben, dass ein Renderziel vom Direct2D-System verwendet wird. Verschiedene Implementierungen von ID2D1RenderTarget verhalten sich möglicherweise anders, wenn BeginDraw aufgerufen wird. Ein ID2D1BitmapRenderTarget kann zwischen BeginDraw/EndDraw-Aufrufen gesperrt sein, ein DXGI-Oberflächenrenderungsziel kann in BeginDraw abgerufen und in EndDraw freigegeben werden, während ein ID2D1HwndRenderTarget möglicherweise mit der Batchverarbeitung bei BeginDraw beginnt und z. B. in EndDraw vorhanden ist.

Die BeginDraw-Methode muss aufgerufen werden, bevor Renderingvorgänge aufgerufen werden können, obwohl Zustandseinstellungs- und Zustandsabrufvorgänge auch außerhalb von BeginDraw/EndDraw ausgeführt werden können.

Nachdem BeginDraw aufgerufen wurde, erstellt ein Renderziel normalerweise einen Batch von Renderingbefehlen, aber verzögert die Verarbeitung dieser Befehle, bis entweder ein interner Puffer voll ist, die Flush-Methode aufgerufen wird oder bis EndDraw aufgerufen wird. Die EndDraw-Methode bewirkt, dass alle batchierten Zeichnungsvorgänge abgeschlossen werden, und gibt dann ein HRESULT zurück, das den Erfolg der Vorgänge und optional den Tagstatus des Renderziels zum Zeitpunkt des Fehlers angibt. Die EndDraw-Methode ist immer erfolgreich: Sie sollte nicht zweimal aufgerufen werden, auch wenn ein vorheriges EndDraw zu einem Fehler von HRESULT geführt hat.

Wenn EndDraw ohne einen übereinstimmenden Aufruf von BeginDraw aufgerufen wird, wird ein Fehler zurückgegeben, der angibt, dass BeginDraw vor EndDraw aufgerufen werden muss.

Durch zweimaliges Aufrufen von BeginDraw auf einem Renderziel wird das Ziel in einen Fehlerzustand versetzt, in dem nichts weiter gezeichnet wird, und gibt beim Aufruf von EndDraw ein entsprechendes HRESULT und Fehlerinformationen zurück.

Beispiele

Im folgenden Beispiel wird ein ID2D1HwndRenderTarget verwendet, um Text in ein Fenster zu zeichnen.

//  Called whenever the application needs to display the client
//  window. This method writes "Hello, World"
//
//  Note that this function will automatically discard device-specific
//  resources if the Direct3D device disappears during function
//  invocation, and will recreate the resources the next time it's
//  invoked.
//
HRESULT DemoApp::OnRender()
{
    HRESULT hr;

    hr = CreateDeviceResources();

    if (SUCCEEDED(hr))
    {
        static const WCHAR sc_helloWorld[] = L"Hello, World!";

        // Retrieve the size of the render target.
        D2D1_SIZE_F renderTargetSize = m_pRenderTarget->GetSize();

        m_pRenderTarget->BeginDraw();

        m_pRenderTarget->SetTransform(D2D1::Matrix3x2F::Identity());

        m_pRenderTarget->Clear(D2D1::ColorF(D2D1::ColorF::White));

        m_pRenderTarget->DrawText(
            sc_helloWorld,
            ARRAYSIZE(sc_helloWorld) - 1,
            m_pTextFormat,
            D2D1::RectF(0, 0, renderTargetSize.width, renderTargetSize.height),
            m_pBlackBrush
            );

        hr = m_pRenderTarget->EndDraw();

        if (hr == D2DERR_RECREATE_TARGET)
        {
            hr = S_OK;
            DiscardDeviceResources();
        }
    }

    return hr;
}

Anforderungen

Weitere Informationen

ID2D1RenderTarget