IDirect3DDevice8::SetCursorProperties

Sets properties for the cursor.

HRESULT SetCursorProperties(
  UINT XHotSpot,
  UINT YHotSpot,
  IDirect3DSurface8* pCursorBitmap
);

Parameters

XHotSpot

[in] X-coordinate offset into the cursor, in pixels from the top-left corner, that is considered the center. When the cursor is given a new position, the image is drawn at an offset from this new position determined by subtracting the hot spot coordinates from the position.

YHotSpot

[in] Y-coordinate offset into the cursor, in pixels from the top-left corner, that is considered the center. When the cursor is given a new position, the image is drawn at an offset from this new position determined by subtracting the hot spot coordinates from the position.

pCursorBitmap

[in] Pointer to an IDirect3DSurface8 interface. This parameter must point to an 8888 ARGB surface (format D3DFORMAT_A8R8G8B8). The contents of this surface will be copied and potentially format-converted into an internal buffer from which the cursor is displayed. The dimensions of this surface must be less than the dimensions of the display mode, and must be a power of two in each direction, although not necessarily the same power of two. The alpha channel must be either 0.0 or 1.0.

Return Values

If the method succeeds, the return value is D3D_OK.

If the method fails, the return value can be D3DERR_INVALIDCALL.

Remarks

Microsoft® Direct3D® cursor functions use either GDI cursor or software emulation, depending on the hardware. Users usually want to respond to a WM_SETCURSOR message. For example, the users might want to write the message handler like this:

case WM_SETCURSOR:
    // Turn off window cursor 
    SetCursor( NULL );
    m_pd3dDevice->ShowCursor( TRUE );
    return TRUE; // prevent Windows from setting cursor to window class cursor
break;

Or users might want to call the IDirect3DDevice8::SetCursorProperties method if they want to change the cursor. See the sample code in the Microsoft DirectX® Graphics C/C++ Samples for more details.

The application can determine what hardware support is available for cursors by examining appropriate members of the D3DCAPS8 structure. Typically, hardware supports only 32x32 cursors. Additionally, when windowed, the system may support only 32x32 cursors. In this case, SetCursorProperties still succeeds, but the cursor may be reduced to that size—the hot spot is scaled appropriately.

Requirements

  Header: Declared in D3d8.h.
  Import Library: Use D3d8.lib.

See Also

IDirect3DDevice8::SetCursorPosition, IDirect3DDevice8::ShowCursor, D3DCAPS8