Método IDirect3DDevice9::GetLight (d3d9.h)

Artigo
08/23/2023

Recupera um conjunto de propriedades de iluminação que este dispositivo usa.

Sintaxe

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

Parâmetros

[in] Index

Tipo: DWORD

Índice baseado em zero da propriedade de iluminação definida para recuperar. Esse método falhará se uma propriedade de iluminação não tiver sido definida para esse índice chamando o método IDirect3DDevice9::SetLight .

[out] unnamedParam2

Tipo: D3DLight9*

Ponteiro para uma estrutura D3DLIGHT9 que é preenchida com o conjunto de parâmetros de iluminação recuperado.

Valor retornado

Tipo: HRESULT

Se o método for bem-sucedido, o valor retornado será D3D_OK. Se o método falhar, o valor retornado poderá ser D3DERR_INVALIDCALL.

Comentários

Esse método não retornará o estado do dispositivo para um dispositivo criado usando D3DCREATE_PUREDEVICE. Se você quiser usar esse método, deverá criar seu dispositivo com qualquer um dos outros valores em D3DCREATE.

Recupere todas as propriedades de uma fonte de luz existente chamando o método IDirect3DDevice9::GetLight para o dispositivo. Ao chamar o método IDirect3DDevice9::GetLight , passe o índice baseado em zero da fonte de luz para a qual as propriedades serão recuperadas como o primeiro parâmetro e forneça o endereço de uma estrutura D3DLIGHT9 como o segundo parâmetro. O dispositivo preenche a estrutura D3DLIGHT9 para descrever as propriedades de iluminação que usa para a fonte de luz nesse índice.


// 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

Se você fornecer um índice fora do intervalo das fontes de luz atribuídas no dispositivo, o método IDirect3DDevice9::GetLight falhará, retornando D3DERR_INVALIDCALL.

Quando você atribui um conjunto de propriedades de luz para uma fonte de luz em uma cena, a fonte de luz pode ser ativada chamando o método IDirect3DDevice9::LightEnable para o dispositivo. Novas fontes de luz são desabilitadas por padrão. O método IDirect3DDevice9::LightEnable aceita dois parâmetros. Defina o primeiro parâmetro como o índice baseado em zero da fonte de luz a ser afetado pelo método e defina o segundo parâmetro como TRUE para habilitar a luz ou FALSE para desabilitá-lo. O exemplo de código a seguir ilustra o uso desse método habilitando a primeira fonte de luz na lista de propriedades de fonte de luz do dispositivo.


// 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

Verifique o membro MaxActiveLights da estrutura D3DCAPS9 ao recuperar as funcionalidades do dispositivo para determinar o número máximo de luzes ativas compatíveis com esse dispositivo.

Se você habilitar ou desabilitar uma luz sem propriedades definidas com IDirect3DDevice9::SetLight, o método IDirect3DDevice9::LightEnable criará uma fonte de luz com as propriedades listadas na tabela a seguir e a habilitará ou desabilita.