Metodo ICompositionDrawingSurfaceInterop2::CopySurface (windows.ui.composition.interop.h)

Articolo
2024-03-13

Legge il contenuto di una superficie di disegno di composizione (o una superficie di disegno virtuale di composizione).

Sintassi

HRESULT CopySurface(
  [in] IUnknown   *destinationResource,
  [in] int        destinationOffsetX,
  [in] int        destinationOffsetY,
  [in] const RECT *sourceRectangle
);

Parametri

[in] destinationResource

Tipo: IUnknown*

Rappresenta la trama Direct3D che riceverà la copia. È necessario aver creato questa risorsa nello stesso dispositivo Direct3D associato a CompositionGraphicsDevice usato per creare l'area di disegno di composizione di origine (o la superficie di disegno virtuale di composizione).

[in] destinationOffsetX

Tipo: int

Coordinata x di un offset (in destinationResource) in cui verrà eseguita la copia. Nessun pixel sopra o a sinistra di questo offset viene modificato dall'operazione di copia. L'argomento non può essere negativo.

[in] destinationOffsetY

Tipo: int

Coordinata y di un offset (in destinationResource) in cui verrà eseguita la copia. Nessun pixel sopra o a sinistra di questo offset viene modificato dall'operazione di copia. L'argomento non può essere negativo.

[in] sourceRectangle

Tipo: const RECT*

Puntatore facoltativo a una costante RECT che rappresenta il rettangolo sulla superficie di origine da copiare. Il rettangolo non può superare i limiti della superficie di origine. Per poter ricevere i pixel richiesti, la risorsa di destinazione deve avere almeno il numero di pixel dei parametri destinationOffsetX e Y più la larghezza/altezza di questo rettangolo.

Se questo parametro è Null, l'intera superficie di origine viene copiata e le dimensioni della superficie di origine vengono usate per convalidare le dimensioni della risorsa di destinazione.

Valore restituito

Tipo: HRESULT

S_OK se ha esito positivo, in caso contrario, restituisce un codice di errore HRESULT che indica il motivo dell'errore. Vedere anche codici di errore COM (interfaccia utente, Audio, DirectX, Codec).

Commenti

Per creare una superficie Direct2D o Direct3D da usare con Windows.UI.Composition, usare le interfacce di interoperabilità della superficie di disegno di composizione . È possibile usare il metodo CopySurface per leggere il contenuto di una superficie di disegno di composizione (o una superficie di disegno virtuale di composizione). CopySurface è una copia sincrona e istantanea da una parte della memoria video a un'altra; non è necessario chiamare Commit.

Per qualsiasi superficie di disegno di composizione specificata (o superficie di disegno virtuale di composizione), l'applicazione può eseguire query su ICompositionDrawingSurfaceInterop2 e chiamare CopySurface in tale interfaccia.

È possibile chiamare CopySurface solo quando non sono presenti aggiornamenti in sospeso per le superfici appartenenti alla stessa superficie CompositionGraphicsDevice dell'area di origine (ICompositionDrawingSurfaceInterop::BeginDraw ha lo stesso requisito). È anche illegale chiamare CopySurface in un'area di disegno di composizione non virtuale che non è mai stata aggiornata, perché il relativo contenuto pixel non è definito. Per le superfici virtuali, poiché vengono allocati in modo sparse, è possibile specificare un rettangolo di origine che interseca le aree non inizializzate della superficie. In tal caso, la chiamata è legale, ma il risultato della copia per quelle aree non inizializzate è indefinito.

Nota

Questa interfaccia è disponibile in Windows 10 versione 1903 (10.0; Build 18362), ma non è definito nel windows.ui.composition.interop.h file di intestazione per tale versione del Windows Software Development Kit (Windows SDK) (SDK). Se si ottiene prima un puntatore a un'interfaccia ICompositionDrawingSurfaceInterop , è possibile eseguire una query su quella (tramite QueryInterface) per un puntatore a un'interfaccia ICompositionDrawingSurfaceInterop2 .

Esempio

Per questo scenario, si prevede un framework che usa CompositionDrawingSurface per concedere la possibilità di eseguire il rendering e comporre contenuto personalizzato in un albero visivo gestito dal framework. Il framework implementa una modalità di risorsa ridotta (da usare, ad esempio, durante la riduzione al minimo o la sospensione dell'applicazione). Quando in questa modalità il framework rilascia la maggior parte degli oggetti di composizione, tra cui tutte le superfici. Prima di rilasciare ogni superficie, tuttavia, il framework estrae i pixel e li comprime ,ad esempio usando il codec PNG, in modo che possa ricostituirli in un secondo momento senza dover richiamare il codice dell'applicazione. Questo esempio di codice mostra una funzione helper che il framework potrebbe implementare per elaborare ogni superficie.

HRESULT CompressSurface(_In_ ICompositionDrawingSurface* surface) 
{ 
    // Get the interop interface.
    ComPtr<ICompositionDrawingSurfaceInterop2> surfaceInterop; 
    RETURN_IF_FAILED(surface.As(&surfaceInterop)); 
 
    // Allocate a staging surface of equal size to the surface to compress.
    SizeInt32 size; 
    RETURN_IF_FAILED(surface->get_Size(&size)); 
 
    // Create a staging texture to receive a copy of the pixels.
    ComPtr<ID3D11Texture2D> stagingTexture; 
    RETURN_IF_FAILED(CreateStagingTexture(size, stagingTexture.GetAddressOf())); 
 
    // Copy the pixels out.
    RETURN_IF_FAILED(surfaceInterop->CopySurface(stagingTexture.get(), 0, 0, nullptr)); 
 
    // Compress the retrieved pixels.
    RETURN_IF_FAILED(CompressTexturePixels(stagingTexture.get())); 
 
    return S_OK; 
} 

HRESULT CreateStagingTexture(const SizeInt32& size, _Outptr_ ID3D11Texture2D** texture) 
{ 
    D3D11_TEXTURE2D_DESC surfaceDesc; 
 
    surfaceDesc.Width = size.Width; 
    surfaceDesc.Height = size.Height; 
    surfaceDesc.MipLevels = 1; 
    surfaceDesc.ArraySize = 1; 
    surfaceDesc.Format = DXGI_FORMAT_R8G8B8A8_UNORM; 
    surfaceDesc.SampleDesc.Count = 1; 
    surfaceDesc.SampleDesc.Quality = 0; 
    surfaceDesc.Usage = D3D11_USAGE_STAGING; 
    surfaceDesc.BindFlags = 0; 
    surfaceDesc.CPUAccessFlags = D3D11_CPU_ACCESS_READ; 
    surfaceDesc.MiscFlags = 0; 

    RETURN_IF_FAILED(g_d3d11Device->CreateTexture2D(surfaceDesc, false, texture)); 

    return S_OK; 
} 

HRESULT CompressTexturePixels(_In_ ID3D11Texture2D* texture) 
{ 
    // ... 
    // Map the texture, feed the pixels to WIC... 
    // ... 
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 10 versione 2004 (10.0; Build 19041)
Server minimo supportato	Windows Server, versione 2004 (10.0; Build 19041)
Piattaforma di destinazione	Windows
Intestazione	windows.ui.composition.interop.h

Condividi tramite