Failures on IDirect3DDevice9::ColorFill

I am only a few months into DirectX programming, but this one just burned me so I thought I would share it:

IDirect3DDevice9::ColorFill will return D3DERR_INVALIDCALL if the rectangle falls outside the surface at all. If you are expecting GDI-type functionality (as I was) where it would just clip the rectangle, think again.

I figured this out by using Source Server and looking at the DX source code: this isnt an option for folks outside of MS. There are other reasons for this return value, so for completeness here they are:

  • Invalid surface
  • Locked surface
  • Invalid rectangle pointer (FYI you can pass NULL as the rect to fill the whole surface)
  • Rectangle falls outside the surface
  • Other stuff that my DX knowledge cannot explain

It is possible that the debug version of DX might tell you why these calls fail: there is code in the source that emits the exact reason as text, somewhere. I don't use debug DX so can't be more specific, sorry.