IDirect3DDevice9::GetLight-Methode (d3d9.h)

Artikel
08/23/2023

Ruft eine Reihe von Beleuchtungseigenschaften ab, die dieses Gerät verwendet.

Syntax

HRESULT GetLight(
  [in]  DWORD     Index,
  [out] D3DLIGHT9 *unnamedParam2
);

Parameter

[in] Index

Typ: DWORD

Nullbasierter Index der abzurufenden Beleuchtungseigenschaft. Diese Methode schlägt fehl, wenn keine Beleuchtungseigenschaft für diesen Index festgelegt wurde, indem die IDirect3DDevice9::SetLight-Methode aufgerufen wird.

[out] unnamedParam2

Typ: D3DLight9*

Zeiger auf eine D3DLIGHT9-Struktur , die mit dem abgerufenen Beleuchtungsparametersatz gefüllt ist.

Rückgabewert

Typ: HRESULT

Wenn die Methode erfolgreich ist, wird der Rückgabewert D3D_OK. Wenn die Methode fehlschlägt, kann der Rückgabewert D3DERR_INVALIDCALL werden.

Hinweise

Diese Methode gibt keinen Gerätestatus für ein Gerät zurück, das mit D3DCREATE_PUREDEVICE erstellt wird. Wenn Sie diese Methode verwenden möchten, müssen Sie Ihr Gerät mit einem der anderen Werte in D3DCREATE erstellen.

Rufen Sie alle Eigenschaften für eine vorhandene Lichtquelle ab, indem Sie die IDirect3DDevice9::GetLight-Methode für das Gerät aufrufen. Übergeben Sie beim Aufrufen der IDirect3DDevice9::GetLight-Methode den nullbasierten Index der Lichtquelle, für die die Eigenschaften als erster Parameter abgerufen werden, und geben Sie die Adresse einer D3DLIGHT9-Struktur als zweiten Parameter an. Das Gerät füllt die D3DLIGHT9-Struktur aus, um die Lichteigenschaften zu beschreiben, die es für die Lichtquelle an diesem Index verwendet.


// Assume d3dDevice is a valid pointer to an IDirect3DDevice9 interface.
HRESULT hr;
D3DLight9 light;
    
// Get the property information for the first light.
hr = pd3dDevice->GetLight(0, &light);
if (SUCCEEDED(hr))
    // Handle Success
else
    // Handle failure

Wenn Sie einen Index außerhalb des Bereichs der im Gerät zugewiesenen Lichtquellen bereitstellen, schlägt die IDirect3DDevice9::GetLight-Methode fehl, wodurch D3DERR_INVALIDCALL zurückgegeben wird.

Wenn Sie einer Lichtquelle in einer Szene eine Reihe von Lichteigenschaften zuweisen, kann die Lichtquelle durch Aufrufen der IDirect3DDevice9::LightEnable-Methode für das Gerät aktiviert werden. Neue Lichtquellen sind standardmäßig deaktiviert. Die IDirect3DDevice9::LightEnable-Methode akzeptiert zwei Parameter. Legen Sie den ersten Parameter auf den nullbasierten Index der Lichtquelle fest, die von der -Methode beeinflusst werden soll, und legen Sie den zweiten Parameter auf TRUE fest, um das Licht oder FALSE zum Deaktivieren zu aktivieren. Im folgenden Codebeispiel wird die Verwendung dieser Methode veranschaulicht, indem die erste Lichtquelle in der Liste der Lichtquelleneigenschaften des Geräts aktiviert wird.


// Assume d3dDevice is a valid pointer to an IDirect3DDevice9 interface.
HRESULT hr;
    
hr = pd3dDevice->LightEnable(0, TRUE);
if (SUCCEEDED(hr))
    // Handle Success
else
    // Handle failure

Überprüfen Sie das MaxActiveLights-Element der D3DCAPS9-Struktur , wenn Sie Gerätefunktionen abrufen, um die maximale Anzahl aktiver Lichter zu ermitteln, die von diesem Gerät unterstützt werden.

Wenn Sie eine Leuchte aktivieren oder deaktivieren, die keine Eigenschaften aufweist, die mit IDirect3DDevice9::SetLight festgelegt sind, erstellt die IDirect3DDevice9::LightEnable-Methode eine Lichtquelle mit den in der folgenden Tabelle aufgeführten Eigenschaften und aktiviert oder deaktiviert sie.