Does `IDXGIOutput5::DuplicateOutput1()` take `enum DXGI_OUTDUPL_FLAG` in the `Flags` parameter?

[MarijnS95]

We were investigating where enum DXGI_OUTDUPL_FLAG could be used (with its only known valid flag value DXGI_OUTDUPL_COMPOSITED_UI_CAPTURE_ONLY = 1), or if it was an accidental unused remnant.

@riverar apparently reverse-engineered an example and confirmed my initial hunch that this value is used for Flags in IDXGIOutput5::DuplicateOutput1(). The documentation still suggests that the Flags value "must be zero" however.

Can anyone clear up whether this is true, and if so:

• Update the documentation;
• Maybe change the parameter type to directly take DXGI_OUTDUPL_FLAG, so that we don't have to hack this in win32metadata via [AssociatedEnum]?

After all DXGI_OUTDUPL_FLAG is an untyped enum which is assumed to be INT by default, mismatching the UINT ABI of the Flags parameter.

---

Note also that I'm trying to propagate this flag usage into win32metadata already via microsoft/win32metadata#1911.

[jenatali]

This isn't really the right place to report this kind of bug, since this repo doesn't actually host DXGI headers, but I don't really have a better place, so 🤷.

You are correct that the Flags should be a DXGI_OUTDUPL_FLAG value or bitmask of values. The usage of strongly-typed fields for flags is relatively recent in the D3D headers, neither D3D11 nor DXGI do that, only D3D12 with the explicit operators defined. I don't think the API header is going to change here.

If you're able/willing, I'd be happy to help review a pull request against the relevant documentation.

[MarijnS95]

For a non Microsofter there isn't really a good place indeed. Started with a draft at MicrosoftDocs/sdk-api#1824, not sure if we can change the ABI or at the very least change the enum type to UINT with an annotation?

[jenatali]

For a non Microsofter there isn't really a good place indeed.

Yeah, I suppose this is as good as any.

or at the very least change the enum type to UINT with an annotation

What do you mean by this?

The important thing is that the function continues to take a 32-bit value (signed/unsigned doesn't strictly matter at the ABI), and we can't/shouldn't make a source-breaking change. Secondary is consistency with the rest of the D3D11/DXGI/Win32 API surface area.

[riverar]

It's not a UINT in the headers so we should fix that in win32metadata.

[MarijnS95]

Heya. MicrosoftDocs/sdk-api#1824 trickled down into the upstream docs yet it appears DXGI_OUTDUPL_FLAG doesn't have a documentation page, and https://learn.microsoft.com/en-us/windows/win32/api/dxgi1_5/nf-dxgi1_5-idxgioutput5-duplicateoutput1 likewise doesn't link to it. Would it be cool/hard to have that?