IDXGIOutputDuplication::GetFramePointerShape method (dxgi1_2.h)

Gets information about the new pointer shape for the current desktop frame.

Syntax

HRESULT GetFramePointerShape(
  [in]  UINT                            PointerShapeBufferSize,
  [out] void                            *pPointerShapeBuffer,
  [out] UINT                            *pPointerShapeBufferSizeRequired,
  [out] DXGI_OUTDUPL_POINTER_SHAPE_INFO *pPointerShapeInfo
);

Parameters

[in] PointerShapeBufferSize

The size in bytes of the buffer that the caller passed to the pPointerShapeBuffer parameter.

[out] pPointerShapeBuffer

A pointer to a buffer to which GetFramePointerShape copies and returns pixel data for the new pointer shape.

[out] pPointerShapeBufferSizeRequired

Pointer to a variable that receives the number of bytes that GetFramePointerShape needs to store the new pointer shape pixel data in the buffer at pPointerShapeBuffer.

For more information about returning the required buffer size, see Remarks.

[out] pPointerShapeInfo

Pointer to a DXGI_OUTDUPL_POINTER_SHAPE_INFO structure that receives the pointer shape information.

Return value

GetFramePointerShape returns:

• S_OK if it successfully retrieved information about the new pointer shape.
• DXGI_ERROR_ACCESS_LOST if the desktop duplication interface is invalid. The desktop duplication interface typically becomes invalid when a different type of image is displayed on the desktop. Examples of this situation are:
  • Desktop switch
  • Mode change
  • Switch from DWM on, DWM off, or other full-screen application
  In this situation, the application must release the IDXGIOutputDuplication interface and create a new IDXGIOutputDuplication for the new content.
• DXGI_ERROR_MORE_DATA if the buffer that the calling application provided was not big enough.
• DXGI_ERROR_INVALID_CALL if the application called GetFramePointerShape without owning the desktop image.
• E_INVALIDARG if one of the parameters to GetFramePointerShape is incorrect; for example, if pPointerShapeInfo is NULL.
• Possibly other error codes that are described in the DXGI_ERROR topic.

Remarks

GetFramePointerShape stores a size value in the variable at pPointerShapeBufferSizeRequired. This value specifies the number of bytes that pPointerShapeBufferSizeRequired needs to store the new pointer shape pixel data. You can use the value in the following situations to determine the amount of memory to allocate for future buffers that you pass to pPointerShapeBuffer:

• GetFramePointerShape fails with DXGI_ERROR_MORE_DATA because the buffer is not big enough.
• GetFramePointerShape supplies a bigger than necessary buffer. The size value returned at pPointerShapeBufferSizeRequired informs the caller how much buffer space was actually used compared to how much buffer space the caller allocated and specified in the PointerShapeBufferSize parameter.

Requirements

See also

IDXGIOutputDuplication