Método IDXGIOutputDuplication::AcquireNextFrame (dxgi1_2.h)

  • Artículo

Indica que la aplicación está lista para procesar la siguiente imagen de escritorio.

Sintaxis

HRESULT AcquireNextFrame(
  [in]  UINT                    TimeoutInMilliseconds,
  [out] DXGI_OUTDUPL_FRAME_INFO *pFrameInfo,
  [out] IDXGIResource           **ppDesktopResource
);

Parámetros

[in] TimeoutInMilliseconds

El intervalo de tiempo de espera en milisegundos. Este intervalo especifica la cantidad de tiempo que este método espera a un nuevo fotograma antes de volver al autor de la llamada. Este método devuelve si transcurre el intervalo y no hay disponible una nueva imagen de escritorio.

Para obtener más información sobre el intervalo de tiempo de espera, vea Comentarios.

[out] pFrameInfo

Puntero a una ubicación de memoria que recibe la estructura de DXGI_OUTDUPL_FRAME_INFO que describe las estadísticas de tiempo y presentación de un fotograma.

[out] ppDesktopResource

Puntero a una variable que recibe la interfaz IDXGIResource de la superficie que contiene el mapa de bits de escritorio.

Valor devuelto

AcquireNextFrame devuelve:

  • S_OK si ha recibido correctamente la siguiente imagen de escritorio.
  • DXGI_ERROR_ACCESS_LOST si la interfaz de duplicación de escritorio no es válida. Normalmente, la interfaz de duplicación de escritorio no es válida cuando se muestra un tipo diferente de imagen en el escritorio. Algunos ejemplos de esta situación son:
    • Conmutador de escritorio
    • Cambio de modo
    • Cambiar de DWM activado, DWM desactivado u otra aplicación de pantalla completa
    En esta situación, la aplicación debe liberar la interfaz IDXGIOutputDuplication y crear una nueva IDXGIOutputDuplication para el nuevo contenido.
  • DXGI_ERROR_WAIT_TIMEOUT si el intervalo de tiempo de espera transcurrido antes de que estuviera disponible el siguiente marco de escritorio.
  • DXGI_ERROR_INVALID_CALL si la aplicación llamada AcquireNextFrame sin liberar el fotograma anterior.
  • E_INVALIDARG si uno de los parámetros de AcquireNextFrame es incorrecto; por ejemplo, si pFrameInfo es NULL.
  • Posiblemente otros códigos de error que se describen en el tema DXGI_ERROR .

Comentarios

Cuando AcquireNextFrame vuelve correctamente, la aplicación que realiza la llamada puede acceder a la imagen de escritorio que AcquireNextFrame devuelve en la variable ppDesktopResource. Si el autor de la llamada especifica un intervalo de tiempo de espera cero en el parámetro TimeoutInMilliseconds , AcquireNextFrame comprueba si hay una nueva imagen de escritorio disponible, devuelve inmediatamente e indica su resultado con el valor devuelto. Si el autor de la llamada especifica un intervalo de tiempo de espera INFINITO en el parámetro TimeoutInMilliseconds , el intervalo de tiempo de espera nunca transcurre.

Nota No puede cancelar la espera que especificó en el parámetro TimeoutInMilliseconds . Por lo tanto, si debe comprobar periódicamente otras condiciones (por ejemplo, una señal de finalización), debe especificar un intervalo de tiempo de espera no INFINITO . Una vez transcurrido el intervalo de tiempo de espera, puede comprobar estas otras condiciones y, a continuación, llamar a AcquireNextFrame de nuevo para esperar al siguiente fotograma.
 
AcquireNextFrame adquiere un nuevo marco de escritorio cuando el sistema operativo actualiza la imagen de mapa de bits de escritorio o cambia la forma o posición de un puntero de hardware. El nuevo marco que acquireNextFrame adquiere podría tener solo la imagen de escritorio actualizada, solo la forma o posición del puntero actualizada, o ambas.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 8 [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2012 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado dxgi1_2.h
Library Dxgi.lib

Consulte también

IDXGIOutputDuplication