Função D3DCompile2 (d3dcompiler.h)
Compila o código HLSL (Linguagem de Sombreador de Alto Nível) da Microsoft em um código de byte para um determinado destino.
Sintaxe
HRESULT D3DCompile2(
[in] LPCVOID pSrcData,
[in] SIZE_T SrcDataSize,
[in, optional] LPCSTR pSourceName,
[in, optional] const D3D_SHADER_MACRO *pDefines,
[in, optional] ID3DInclude *pInclude,
[in] LPCSTR pEntrypoint,
[in] LPCSTR pTarget,
[in] UINT Flags1,
[in] UINT Flags2,
[in] UINT SecondaryDataFlags,
[in, optional] LPCVOID pSecondaryData,
[in] SIZE_T SecondaryDataSize,
[out] ID3DBlob **ppCode,
[out, optional] ID3DBlob **ppErrorMsgs
);
Parâmetros
[in] pSrcData
Tipo: LPCVOID
Um ponteiro para dados de sombreador não compilados (código ASCII HLSL).
[in] SrcDataSize
Tipo: SIZE_T
O tamanho, em bytes, do bloco de memória para o qual pSrcData aponta.
[in, optional] pSourceName
Tipo: LPCSTR
Um ponteiro opcional para uma cadeia de caracteres terminada em nulo constante que contém o nome que identifica os dados de origem a serem usados em mensagens de erro. Se não for usado, defina como NULL.
[in, optional] pDefines
Tipo: const D3D_SHADER_MACRO*
Uma matriz opcional de estruturas de D3D_SHADER_MACRO que definem macros de sombreador. Cada definição de macro contém um nome e uma definição terminada em nulo. Se não for usado, defina como NULL. A última estrutura na matriz serve como um terminador e deve ter todos os membros definidos como NULL.
[in, optional] pInclude
Tipo: ID3DInclude*
Um ponteiro para uma interface ID3DInclude que o compilador usa para manipular arquivos de inclusão. Se você definir esse parâmetro como NULL e o sombreador contiver um #include, ocorrerá um erro de compilação. Você pode passar a macro D3D_COMPILE_STANDARD_FILE_INCLUDE , que é um ponteiro para um manipulador de inclusão padrão. Esse manipulador de inclusão padrão inclui arquivos relativos ao diretório atual e arquivos relativos ao diretório do arquivo de origem inicial. Ao usar D3D_COMPILE_STANDARD_FILE_INCLUDE, você deve especificar o nome do arquivo de origem no parâmetro pSourceName ; o compilador derivará o diretório relativo inicial do pSourceName.
#define D3D_COMPILE_STANDARD_FILE_INCLUDE ((ID3DInclude*)(UINT_PTR)1)
[in] pEntrypoint
Tipo: LPCSTR
Um ponteiro para uma cadeia de caracteres terminada em nulo constante que contém o nome da função de ponto de entrada do sombreador em que a execução do sombreador começa. Quando você compila um efeito, D3DCompile2 ignora pEntrypoint; Recomendamos que você defina pEntrypoint como NULL porque é uma boa prática de programação definir um parâmetro de ponteiro como NULL se a função chamada não o usar.
[in] pTarget
Tipo: LPCSTR
Um ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica o destino do sombreador ou o conjunto de recursos de sombreador para compilar. O destino do sombreador pode ser um modelo de sombreador (por exemplo, modelo de sombreador 2, modelo de sombreador 3, modelo de sombreador 4 ou modelo de sombreador 5). O destino também pode ser um tipo de efeito (por exemplo, fx_4_1). Para obter informações sobre os destinos aos quais vários perfis dão suporte, consulte Especificando destinos do compilador.
[in] Flags1
Tipo: UINT
Uma combinação de constantes de compilação D3D do sombreador que são combinadas usando uma operação OR bit a bit. O valor resultante especifica como o compilador compila o código HLSL.
[in] Flags2
Tipo: UINT
Uma combinação de constantes de efeito de compilação D3D que são combinadas usando uma operação OR bit a bit. O valor resultante especifica como o compilador compila o efeito. Quando você compila um sombreador e não um arquivo de efeito, D3DCompile2 ignora Flags2; Recomendamos que você defina Flags2 como zero porque é uma boa prática de programação definir um parâmetro nãopointer como zero se a função chamada não o usar.
[in] SecondaryDataFlags
Tipo: UINT
Uma combinação dos sinalizadores a seguir que são combinados usando uma operação OR bit a bit. O valor resultante especifica como o compilador compila o código HLSL.
| Sinalizador | Descrição |
|---|---|
| D3DCOMPILE_SECDATA_MERGE_UAV_SLOTS (0x01) | Mesclar slots de exibição de acesso não ordenado (UAV) nos dados secundários para os quais o parâmetro pSecondaryData aponta. |
| D3DCOMPILE_SECDATA_PRESERVE_TEMPLATE_SLOTS (0x02) | Preserve os slots de modelo nos dados secundários para os quais o parâmetro pSecondaryData aponta. |
| D3DCOMPILE_SECDATA_REQUIRE_TEMPLATE_MATCH (0x04) | Exija que os modelos nos dados secundários que o parâmetro pSecondaryData aponte para corresponder quando o compilador compila o código HLSL. |
Se pSecondaryData for NULL, defina como zero.
[in, optional] pSecondaryData
Tipo: LPCVOID
Um ponteiro para dados secundários. Se você não passar dados secundários, defina como NULL. Use esses dados secundários para alinhar slots UAV em dois sombreadores. Suponha que o sombreador A tenha UAVs e eles estejam associados a alguns slots. Para compilar o sombreador B de modo que os UAVs com os mesmos nomes sejam mapeados em B para os mesmos slots que em A, passe o código de byte de A para D3DCompile2 como os dados secundários.
[in] SecondaryDataSize
Tipo: SIZE_T
O tamanho, em bytes, do bloco de memória para o qual pSecondaryData aponta. Se pSecondaryData for NULL, defina como zero.
[out] ppCode
Tipo: ID3DBlob**
Um ponteiro para uma variável que recebe um ponteiro para a interface ID3DBlob que você pode usar para acessar o código compilado.
[out, optional] ppErrorMsgs
Tipo: ID3DBlob**
Um ponteiro para uma variável que recebe um ponteiro para a interface ID3DBlob que você pode usar para acessar mensagens de erro do compilador ou NULL se não houver erros.
Retornar valor
Tipo: HRESULT
Retorna um dos códigos de retorno do Direct3D 11.
Comentários
A diferença entre D3DCompile2 e D3DCompile é que D3DCompile2 usa alguns parâmetros opcionais (SecondaryDataFlags, pSecondaryData e SecondaryDataSize) que podem ser usados para controlar alguns aspectos de como o bytecode é gerado. Consulte as descrições desses parâmetros para obter mais detalhes. Caso contrário, não há diferença para a eficiência do código de byte gerado entre D3DCompile2 e D3DCompile.
Compilando sombreadores para UWP
Para compilar sombreadores offline, a abordagem recomendada é usar a ferramenta do compilador effect. Se você não conseguir compilar todos os sombreadores antecipadamente, considere compilar os mais caros e os que sua inicialização e os caminhos mais sensíveis ao desempenho exigem e compilar o restante em runtime. Você pode usar um processo semelhante ao seguinte para compilar um sombreador carregado ou gerado em um aplicativo UWP sem bloquear o thread da interface do usuário.
Usando o Visual Studio 2015+ para desenvolver o aplicativo UWP, adicione o novo item "shader.hlsl".
- Na exibição Pasta de Solução do Visual Studio, selecione o item shaders.hlsl , clique com o botão direito do mouse em Propriedades.
- Verifique se o conteúdo do item está definido como Sim.
- Verifique se o Tipo de Item está definido como Texto.
- Adicione um botão ao XAML, nomeie-o adequadamente ("TheButton" neste exemplo) e adicione um manipulador click .
Agora, adicione estes inclusões ao arquivo .cpp:
#include <ppltasks.h> #include <d3dcompiler.h> #include <Robuffer.h>Use o código a seguir para chamar D3DCompile2. Observe que não há verificação ou tratamento de erros aqui e também que esse código demonstra que você pode fazer E/S e compilação em segundo plano, o que deixa sua interface do usuário mais responsiva.
void App1::DirectXPage::TheButton_Click(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
std::shared_ptr<Microsoft::WRL::ComPtr<ID3DBlob>> blobRef = std::make_shared<Microsoft::WRL::ComPtr<ID3DBlob>>();
// Load a file and compile it.
auto fileOp = Windows::ApplicationModel::Package::Current->InstalledLocation->GetFileAsync(L"shader.hlsl");
create_task(fileOp).then([this](Windows::Storage::StorageFile^ file) -> IAsyncOperation<Windows::Storage::Streams::IBuffer^>^
{
// Do file I/O in background thread (use_arbitrary).
return Windows::Storage::FileIO::ReadBufferAsync(file);
}, task_continuation_context::use_arbitrary())
.then([this, blobRef](Windows::Storage::Streams::IBuffer^ buffer)
{
// Do compilation in background thread (use_arbitrary).
// Cast to Object^, then to its underlying IInspectable interface.
Microsoft::WRL::ComPtr<IInspectable> insp(reinterpret_cast<IInspectable*>(buffer));
// Query the IBufferByteAccess interface.
Microsoft::WRL::ComPtr<Windows::Storage::Streams::IBufferByteAccess> bufferByteAccess;
insp.As(&bufferByteAccess);
// Retrieve the buffer data.
byte *pBytes = nullptr;
bufferByteAccess->Buffer(&pBytes);
Microsoft::WRL::ComPtr<ID3DBlob> blob;
Microsoft::WRL::ComPtr<ID3DBlob> errMsgs;
D3DCompile2(pBytes, buffer->Length, "shader.hlsl", nullptr, nullptr, "main", "ps_5_0", 0, 0, 0, nullptr, 0, blob.GetAddressOf(), errMsgs.GetAddressOf());
*blobRef = blob;
}, task_continuation_context::use_arbitrary())
.then([this, blobRef]()
{
// Update UI / use shader on foreground thread.
wchar_t message[40];
swprintf_s(message, L"blob is %u bytes long", (unsigned)(*blobRef)->GetBufferSize());
this->TheButton->Content = ref new Platform::String(message);
}, task_continuation_context::use_current());
}
Requisitos
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Windows |
| Cabeçalho | d3dcompiler.h |
| Biblioteca | D3DCompiler.lib |
| DLL | D3DCompiler_47.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de