struttura D3DHAL_DRAWPRIMITIVES2DATA (d3dhal.h)

Articolo
02/06/2025

La struttura D3DHAL_DRAWPRIMITIVES2DATA contiene le informazioni richieste dalla funzione D3dDrawPrimitives2 per il rendering delle primitive.

Sintassi

typedef struct _D3DHAL_DRAWPRIMITIVES2DATA {
  ULONG_PTR                 dwhContext;
  DWORD                     dwFlags;
  DWORD                     dwVertexType;
  LPDDRAWI_DDRAWSURFACE_LCL lpDDCommands;
  DWORD                     dwCommandOffset;
  DWORD                     dwCommandLength;
  union {
    LPDDRAWI_DDRAWSURFACE_LCL lpDDVertex;
    LPVOID                    lpVertices;
  };
  DWORD                     dwVertexOffset;
  DWORD                     dwVertexLength;
  DWORD                     dwReqVertexBufSize;
  DWORD                     dwReqCommandBufSize;
  LPDWORD                   lpdwRStates;
  union {
    DWORD   dwVertexSize;
    HRESULT ddrval;
  };
  DWORD                     dwErrorOffset;
} D3DHAL_DRAWPRIMITIVES2DATA;

Membri

dwhContext

Specifica l'handle di contesto del dispositivo Direct3D.

dwFlags

Specifica i flag che forniscono istruzioni aggiuntive al driver o forniscono informazioni dal driver. Questo membro può essere un OR bit per bit dei valori seguenti:

Valore	Significato
D3DHALDP2_EXECUTEBUFFER	Il comando e i vertex buffer sono stati creati nella memoria di sistema. Il driver deve aggiornare la matrice di stato a cui punta lpdwRStates. Questo flag è impostato solo da Direct3D.
D3DHALDP2_REQCOMMANDBUFSIZE	Il driver deve essere in grado di aumentare il buffer dei comandi corrente almeno delle dimensioni specificate in dwReqCommandBufSize. I driver che non supportano il multibuffering dei buffer dei comandi possono ignorare questo flag. Questo flag è impostato solo da Direct3D.
D3DHALDP2_REQVERTEXBUFSIZE	Il driver deve essere in grado di allocare un buffer dei vertici di almeno le dimensioni specificate in dwReqCommandBufSize. I driver che non supportano il multibuffering dei buffer dei vertici possono ignorare questo flag. Questo flag è impostato solo da Direct3D.
D3DHALDP2_SWAPCOMMANDBUFFER	Il driver può scambiare il buffer a cui punta lpDDCommands con un nuovo buffer dei comandi e restituire immediatamente, elaborando in modo asincrono il buffer originale mentre Direct3D riempie il nuovo buffer dei comandi. I driver che non supportano il multibuffering dei buffer dei comandi possono ignorare questo flag. Questo flag è impostato solo da Direct3D.
D3DHALDP2_SWAPVERTEXBUFFER	Il driver può scambiare il buffer a cui punta lpDDVertex o lpVertices con un nuovo buffer dei vertici e restituire immediatamente, elaborando il buffer originale in modo asincrono mentre Direct3D riempie il nuovo buffer dei vertici. I driver che non supportano il multibuffering dei buffer dei vertici possono ignorare questo flag. Questo flag è impostato solo da Direct3D.
D3DHALDP2_USERMEMVERTICES	Il membro lpVertices è valido in modo che il driver debba ottenere i dati dei vertici dalla memoria allocata dall'utente a cui punta lpVertices. Questo flag è impostato solo da Direct3D.
D3DHALDP2_VIDMEMCOMMANDBUF	Il buffer dei comandi allocato dal driver come buffer di scambio non si trova nella memoria di sistema. Questo flag può essere impostato dai driver che supportano il multibuffering dei buffer dei comandi.
D3DHALDP2_VIDMEMVERTEXBUF	Il vertex buffer allocato dal driver come buffer di scambio non è in memoria di sistema. Questo flag può essere impostato dai driver che supportano il multibuffering dei vertex buffer.

dwVertexType

Identifica il FVF dei dati nel vertex buffer; ovvero dwVertexType specifica i campi dati per vertice presenti nel vertex buffer a cui lpDDVertex o lpVertices punti. Questo membro può essere un OR bit per bit dei valori nella tabella seguente. Viene impostato solo uno dei flag D3DFVF_TEXx.

Valore	Significato
D3DFVF_DIFFUSE	Ogni vertice ha un colore diffuso.
D3DFVF_SPECULAR	Ogni vertice ha un colore speculare.
D3DFVF_TEX0	Nessuna coordinata di trama viene fornita con i dati dei vertici.
D3DFVF_TEX1	Ogni vertice ha un set di coordinate di trama.
D3DFVF_TEX2	Ogni vertice ha due set di coordinate di trama.
D3DFVF_TEX3	Ogni vertice ha tre set di coordinate di trama.
D3DFVF_TEX4	Ogni vertice ha quattro set di coordinate di trama.
D3DFVF_TEX5	Ogni vertice ha cinque set di coordinate di trama.
D3DFVF_TEX6	Ogni vertice ha sei set di coordinate di trama.
D3DFVF_TEX7	Ogni vertice ha sette set di coordinate di trama.
D3DFVF_TEX8	Ogni vertice ha otto set di coordinate di trama.
D3DFVF_XYZRHW	Ogni vertice ha coordinate x, y, z e w. Questo flag è sempre impostato.

lpDDCommands

dwCommandOffset

dwCommandLength

Specifica il numero di byte di dati di comando validi nella superficie che lpDDCommands punta a partire da dwCommandOffset.

lpDDVertex

Punta alla struttura DD_SURFACE_LOCAL che identifica la superficie DirectDraw contenente i dati dei vertici quando il flag D3DHALDP2_USERMEMVERTICES non è impostato in dwFlags. Forma un'unione con lpVertices.

lpVertices

Punta a un blocco di memoria in modalità utente contenente i dati dei vertici quando il flag di D3DHALDP2_USERMEMVERTICES è impostato in dwFlags.

dwVertexOffset

Specifica il numero di byte nella superficie a cui punta lpDDVertex o lpVertices all'inizio dei dati del vertice.

dwVertexLength

Specifica il numero di vertici a cui sono presenti dati validi nella superficie a cui punta lpDDVertex o lpVertices. Questi dati validi iniziano da dwVertexOffset.

dwReqVertexBufSize

Specifica il numero minimo di byte che il driver deve allocare per il buffer dei vertici di scambio. Questo membro è valido solo quando è impostato il flag D3DHALDP2_REQVERTEXBUFSIZE. I driver che non supportano il multibuffering dei buffer dei vertici devono ignorare questo membro.

dwReqCommandBufSize

Specifica il numero minimo di byte per cui il driver deve aumentare il buffer dei comandi di scambio. Questo membro è valido solo quando è impostato il flag D3DHALDP2_REQCOMMANDBUFSIZE. I driver che non supportano il multibuffering dei buffer dei comandi devono ignorare questo membro.

lpdwRStates

Punta a una matrice di stato di rendering che il driver deve aggiornare quando analizza i comandi di stato di rendering dal buffer dei comandi. Il driver deve aggiornare questa matrice solo quando il flag di D3DHALDP2_EXECUTEBUFFER è impostato in dwFlags. Il driver deve usare i tipi enumerati D3DRENDERSTATETYPE per aggiornare l'elemento appropriato della matrice di stato di rendering.

dwVertexSize

Specifica le dimensioni di ogni vertice, in byte. Questo membro forma un'unione con ddrval.

ddrval

Specifica il percorso in cui il driver scrive il valore restituito di D3dDrawPrimitives2. D3D_OK indica l'esito positivo. In caso contrario, il driver deve restituire il codice di errore appropriato D3DERR_Xxx. Per altre informazioni, vedere codici restituiti per i callback dei driver Direct3D.

Valore	Significato
D3D_OK	Operazione completata correttamente.
D3DERR_COMMAND_UNPARSED	Il driver richiede che il runtime Direct3D analizzi il buffer di esecuzione.

dwErrorOffset

Ogni D3DHAL_DP2RESPONSEQUERY è seguita dai dati seguenti correlati alla query:

BOOL per D3DQUERYTYPE_EVENT
DWORD per D3DQUERYTYPE_OCCLUSION
struttura D3DDEVINFO_VCACHE per D3DQUERYTYPE_VCACHE

Osservazioni

Si noti che il membro dwVertexOffset specifica i valori in byte; il membro dwVertexLength specifica i valori nei vertici.

Per calcolare i dati validi, in byte, presenti nella superficie in lpDDVertex o lpVertices, moltiplicare il valore in dwVertexLength per il valore in dwVertexSize.