terrafx/terrafx.interop.windows

Interop bindings for Windows.

TerraFX.Interop.Windows

Interop bindings for Windows.

Packages are available at: https://github.com/orgs/terrafx/packages or via the NuGet Feed URL: https://pkgs.terrafx.dev/index.json

Table of Contents

• Code of Conduct
• License
• Contributing
• Goals
• Languages and Frameworks

Code of Conduct

ClangSharp and everyone contributing (this includes issues, pull requests, the wiki, etc) must abide by the .NET Foundation Code of Conduct: https://dotnetfoundation.org/about/code-of-conduct.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected].

License

Copyright © Tanner Gooding and Contributors. Licensed under the MIT License (MIT). See LICENSE in the repository root for more information.

Contributing

If you are looking to contribute you should read our Contributing documentation.

Goals

TerraFX is aiming to be a cross-platform framework for developing multimedia- based applications.

• We plan on primarily supporting Linux and Windows and are looking at the possibility of supporting MacOS as well.
• We plan on providing an API that abstracts over the various lower-level graphics, audio, and windowing libraries APIs and makes them easy to use.

Languages and Frameworks

TerraFX uses C# as its primary development language and .NET Core as our primary target framework.

.NET Foundation

This project is supported by the .NET Foundation.

terrafx.interop.windows's Issues

[Proposal] Expose the Debug Interface Access API

Description

https://docs.microsoft.com/en-us/visualstudio/debugger/debug-interface-access/debug-interface-access-sdk
This is a set of COM APIs covering the parsing of PDB files. The headers are typically located in %VSInstallDir%\DIA SDK\include (when the C/C++ tools are installed). It may also be worthwhile to expose the DbgHelp APIs, which are higher level wrappers over DIA.

Rationale

I make use of DIA in several projects I'm working on with C# where performance is a significant factor, thus it would be immensely helpful for the APIs to be available in low-level blittable form via TerraFX.

Drawbacks

The msdia*.dll (and dbghelp.dll) libraries are not typically available from PATH, and are usually only present when Visual Studio has been installed with the C/C++ tools workload. This could complicate general usage (though I suppose it could be mitigated with a NuGet package providing the DLLs?), since you would likely need to register a custom resolver for the APIs to work.

Alternatives

Currently you can generate a (non-blittable) binding for DIA by using midl and tlbimp, but several of the APIs end up being unwieldy (or potentially unusable) due to the resulting signatures using managed arrays, refs, etc.

[QUESTION] Offscreen graphics? (No attached Application window)

Need a console program sample for offscreen graphics/compute, where no Window is involved.
Currently no idea how to create a device from GraphicsAdapter without a window.

Add COM interface IID as public const string

For example:

[Guid(ID2D1Factory.IIDString)]
public struct ID2D1Factory : ID2D1Factory.Interface
{
    public const string IIDString = "06152247-6F50-465A-9245-118BFD3B6007";
}

This would allow me to not need my own const string definitions of these guids, which helps power my code generator, and a few corner cases at runtime where I need to map from a wrapper interface Type to its associated native COM IID:

[NativeInterfaceID(Direct2D1InterfaceID.ID2D1Factory)]
[PreferDerivedInterface(typeof(IDirect2DFactory1))]
public interface IDirect2DFactory
    : IObjectRef
{
}

// I could remove this class
internal static class Direct2D1InterfaceID
{
    public const string ID2D1Factory = "06152247-6f50-465a-9245-118bfd3b6007";
}

I may be able to rewrite my code to not need the string representation, but it's still useful for applying attributes that use Guids. You need a compile-time constant, which means a string.

For my purposes, the format of the guid doesn't matter, whether it's "06152247-6F50-465A-9245-118BFD3B6007" or "{06152247-6F50-465A-9245-118BFD3B6007}".

[QUESTION] Possible bug in handling strings?

Hello there,

i am currently working on interop code with windows again for a home project and by looking for samples and already present libraries i came around this project which is inspiring. The most annoying/expensive of the base types happens to be string and making it blittable would improve performance.

Now the question: In the sample application https://github.com/terrafx/terrafx.interop.windows/blob/main/samples/DirectX/Shared/Win32Application.cs

            fixed (char* lpszClassName = "DXSampleClass")
            fixed (char* lpWindowName = pSample.Name)
            {
                ...

                // Initialize the window class.
                var windowClass = new WNDCLASSEXW {
                    cbSize = (uint)sizeof(WNDCLASSEXW),
                    style = CS_HREDRAW | CS_VREDRAW,
                    lpfnWndProc = wndProc,
                    hInstance = hInstance,
                    hCursor = LoadCursorW(IntPtr.Zero, (ushort*)IDC_ARROW),
                    lpszClassName = (ushort*)lpszClassName
                };
                ...
            }

A string is fixed and then casted to a ushort pointer in the windowClass, which means the default marshaller would not touch it.
The native type is LPCWSTR which has to be null-terminated.

Is this using undefined/undocumented behavior or how it is made sure, that there is an implicit 0 ushort at the end of the string? If this behavior changes at some point, it could lead to strange bugs as far as i know.

Best regards

List of things for "the analyzer" to point out

We can keep track of things that can't really be solved in source, but can be flagged by an analyzer.

• Incorrectly using Unsafe.SizeOf<T>() or Marshal.SizeOf(typeof(T)) on structs like SHELLEXECUTEINFOW. It can produce the wrong size on certain platforms, and T.SizeOf should be used instead.

Missing GET_X_LPARAM and GET_Y_LPARAM

I went to go use these "macros" in my code and they're missing from TerraFX

GET_X_LPARAM() maps to LOWORD(), while GET_Y_LPARAM() maps to HIWORD()

Add SupportedOSPlatformAttribute as applicable

Description

Decorate every API in the code base with SupportedOSPlatformAttribute specifying in which Windows version that feature was introduced in. This causes Roslyn to detect uses of Windows APIs that are newer than the version specified in the TargetFramework, and to issue a compiler warning unless the callsite has a suitable version test.

Rationale

I like to make my apps run on the oldest version of Windows they can given their API closure. This closure is the complete set of Windows APIs my application calls that are absolutely required for the app to work. “Absolutely required” means “app will crash without it” or “app features can’t be implemented without it.” I am really quite strict about considering any UI fluff to be optional. The coolness of the app’s UI should depend on the version of Windows being used, not the other way around. And yes, if my app only references APIs that were available in Windows Vista, I do want to make my app able to run on Windows Vista, despite how old it is! (Windows XP is a lost cause, though, because it’s too different from Vista and later. Vista is as far back as I will go.)

Proposed API

You use SupportedOSPlatformAttribute like so:

[SupportedOSPlatform("windows5.2")] // introduced in Windows XP or earlier
[SupportedOSPlatform("windows6.0")] // introduced in Windows Vista
[SupportedOSPlatform("windows6.1")] // introduced in Windows 7
[SupportedOSPlatform("windows6.2")] // introduced in Windows 8
[SupportedOSPlatform("windows10.0.xxxxx")] // introduced in Windows 10 build xxxxx

Drawbacks

I dunno? This might take a lot of typing? 😅

Alternatives

I could check docs.microsoft.com every time I call a new Win32 API and use what I find there to craft version-check constructs, but then the compiler wouldn’t warn me if I happen to forget one.

Add [SuppressGCTransition] to D3D12 command recording methods

Description (optional)

Introduce [SuppressGCTransition] to calls that record commands on a command list. This does not include Close/Reset commands, nor any commands from parent types (e.g Get/SetPrivateData.

Rationale

These are some of the hottest methods in the API (this is why they don't return error codes etc). Constant GC transitions while calling them are liable to have a non-negligible impact on performance.

Drawbacks

Naturally, SuppressGCTransition has risks. In my experience, all the methods on these list have trivial execution times (sub 1-us), and they are explicitly single threaded, so they should not be taking any syncprims.

Other thoughts

An interesting alternative is some sort of method to "batch" the transitions via an API. E.g instead of what is implicitly

EnterPreemptive();
list->IASetVertexBuffers(...);
ExitPreemptive();

EnterPreemptive();
list->OMSetDepthBounds(...);
ExitPreemptive();

EnterPreemptive();
list->Draw(...);
ExitPreemptive();

being able to explicitly do

EnterPreemptive();
 
list->IASetVertexBuffers(...);
list->OMSetDepthBounds(...);
list->Draw(...);

ExitPreemptive();

Need binding for CoCreateInstance

Many (most?) COM interfaces in TerraFX.Interop.Windows don't have factory functions. A good example of this is IWICImagingFactory. Online tutorials use CoCreateInstance, but this function is missing in TerraFX.Interop.Windows. Would you mind adding a binding for it? There may also be other functions that are often used when interoping with COM but I only just started creating COM objects this way, so you'd know much better than I would.

CoCreateInstance lives in combaseapi.h.

It looks like there are also other things that might need mappings, such as the types in WTypesbase.h. An example of this is CLSCTX_INPROC_SERVER, which is apparently often passed to CoCreateInstance.

[IDEA] Add helpers for creating D3D12 pipeline state streams

D3D12 has a mechanism known as "pipeline state streams" where essentially you assemble a stream of commands for the driver and GPU to create a pipeline state object (pso) from. This mechanism is very flexible and extensible, but unfortunately requires more work from the application programmer. Therefore, I'd like to propose adding some helpers for creating pipeline state streams

The D3D12 helper library d3dx12.h already has helper structs for all the commands in a pipeline state stream. I propose that we add those structs to this library as-is

We'd have to manually convert those structs to C#, work I've already started in my hobby engine (line numbers might change as I develop my code further). I plan to open a PR with my structs once they're complete

[Bug] Stack Overflow in D3D12.HelloTriangle

Steps to reproduce:

1. Open TerraFX.Samples.DirectX.sln in Visual Studio 2019
2. Properties->Debug->App Arguments: D3D12.HelloTriangle
3. Run in Debug AnyCpu mode (F5) and confirm the triangle shows up
4. Run Debug->Graphics->Start Graphics Debugging, wait for the triangle to show up
5. Click [Capture Frame]
   => Stack Overflow error (see screenshot below)
   Strange enough, the call stack is short, so the stack that is overflowing is not the call stack.

Missing RGB macro

I'm not using this, I just noticed its absence.

https://docs.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-rgb

From wingdi.h :
#define RGB(r,g,b) ((COLORREF)(((BYTE)(r)|((WORD)((BYTE)(g))<<8))|(((DWORD)(BYTE)(b))<<16)))

Introduce package for beta/insider SDKs

Description (optional)

Versions of the bindings which use the insider preview SDKs.

Rationale

There's a lot of stuff in the insider SDKs that is useful for developers to experiment with.

Proposed API

N/A

Drawbacks

None

Alternatives

Just having the insider content in the main package

[BUG] fresh build looks for .NET CORE 5.0

Windows 10 Pro, Visual Studio 2019, .NET CORE 3.0 and 3.1 installed via the Visual Studio installer.
terrafx repo cloned, opened TerraFX.Interop.Windows.sln tried to run TerraFX.Samples.DirectX in Debug AnyCpu mode.

I got 117 identical errors complaining that

The current .NET SDK does not support targeting .NET Core 5.0. Either target .NET Core 3.1 or lower, or use a version of the .NET SDK that supports .NET Core 5.0.

All pointing back to the file

C:\ProgramFiles\dotnet\sdk\3.1.201\Sdks\Microsoft.NET.Sdk\targets\Microsoft.NET.TargetFrameworkInference.targets

Why is it thinking .Net Core 5.0 is configured as target?

PS: Ok, the next version of .Net Core will be .Net 5.0 (no core). I installed the preview 3 and rebuilt the solutino. Still same error.

[PROPOSAL] Update the contributing docs to include minimum tooling requirements.

Rationale

Developers looking to contribute may not always use the command line or stay up to date with the latest tooling/previews and so they may run into accidental issues when the repo moves forward.
As such, it would be beneficial if the contributing docs and potentially the readme clearly called out the tooling requirements for the repository.
This includes both the command line and graphical experience via an IDE like Visual Studio.

Alternatives

Some of this could be simplified by enabling experimental work as opt-in or by doing it in a separate branch. However, developers would still want to know those dependencies and so something like the above may still be required.

SceneModel as reusable render state for GUI samples in WinForms, WPF, etc

[IDEA] refactor WinForms sample when we have a WPF or other GUI sample such that in the UI library specific code is minimal code. All the Dx12 rendering setup should be in a separate scene model that is keeping the render configuration state. The GUI just provides a way to update that state. This will maximize the code reuse between the different GUI library samples.

[IDEA] Introduce PIX bindings

Idea

Introduce PIX bindings for this repo

Rationale

PIX is the officially recommended debugger for DX and support is useful

Proposed API

// CPU only
void PIXBeginEvent(ulong color, ushort* formatString, __arglist);

// GPU and CPU
void PIXBeginEvent(ID3D12CommandList* commandList, ulong color, ushort* formatString, __arglist);
void PIXBeginEvent(ID3D12CommandQueue* commandQueue, ulong color, ushort* formatString, __arglist);

// CPU only
void PIXEndEvent();
        
// GPU and CPU
void PIXEndEvent(ID3D12CommandList* commandList);
void PIXEndEvent(ID3D12CommandQueue* commandQueue);

// CPU
void PIXSetMarker(ulong color, ushort* formatString, __arglist);

// GPU and CPU
void PIXSetMarker(ID3D12GraphicsCommandList* commandList, ulong color, ushort* formatString, __arglist);
void PIXSetMarker(ID3D12CommandQueue* commandQueue, ulong color, ushort* formatString, __arglist);

// Could be implemented with a IDisposable struct and a using

PIXScopedEvent(ulong color, ushort*  formatString, __arglist);
PIXScopedEvent(ID3D12GraphicsCommandList* commandList, ulong color, ushort*  formatString, __arglist);
PIXScopedEvent(ID3D12CommandQueue* commandQueue, ulong color, ushort* formatString, __arglist);

void PIXReportCounter(ushort* name, float value);

void PIXNotifyWakeFromFenceSignal(HANDLE event);

// Returns a color for a PIX event or marker from the specified red, green and blue values
int PIX_COLOR(byte r, byte g, byte b);

// Returns an arbitrary color value for the given index.
// PIX allocates a unique color for each index.
uint PIX_COLOR_INDEX(byte i);

Drawbacks

I am not sure about the copyright status of PIX, and obviously while calling the native functions is fine, porting the header ones might be an issue

XInput 1.4 support

I manually created my own bindings for XInput.h but it would be great to use them through TerraFX, instead.

DirectML bindings

[IDEA] Please create bindings for DirectML so that C# code can run neural networks.

Consider COLORREF helper struct e.g. Windows.CreateSolidBrush()

this is typedef'd as DWORD in wtypes.h

You also mentioned LPARAM and WPARAM could be treated similarly

RegisterPowerSettingNotification() returns void* instead of IntPtr?

https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-registerpowersettingnotification

The docs show it returning a HPOWERNOTIFY, a "handle" type, so I was expecting this to return IntPtr like all the other handle-y methods.

I use this to get notifications about battery saver mode so I can ramp down (or turn off) animations in the UI. I put the return value into a SafeHandle-derived class that calls UnregisterPowerSettingNotification to free the handle.

(Oh, and UnregisterPowerSettingNotification should take IntPtr instead of void* as well)

GUI samples with configurable target frame rate

[Idea] Add to the GUI samples (WinForms and similar) a timer to implement rendering at a configurable target frame rate. By default the frame rate should be 60Hz. This implies that something in the rendering must change every frame to demonstrate that we are rendering at that rate.

However, mouse interaction should also result in a visible change of the rendering. Both can be done by updating different rendering parameters. The render timer can change the colors of the shape, and the mouse interaction can change the position or orientation.

[IDEA] .Net 5.0 + Dx12 Hello World

TerraFx seems to be the ideal project for demonstrating best practices using modern Microsoft solutions for modern apps.
I see as a personal immediate need, that probably is actually quite common, to have to write a Windows 10 app that should have a fluid GUI (.NET 5.0 with WinUI 3.0 would be ideal) and some panels/viewports in the window with high performance 3D graphics (D3D12 would be ideal) but the graphics viewports are not a game but a technical interface and thus also need a toolstrip on the side (ideally semitransparent) and a mouse right click context menu.
It seems that TerraFx already has most of these technologies combined and would have expanded appeal if there was a Hello World that would demonstrate how to use them together.

A minimal desirable set of functionality would be:

1. A main window using XAML that can be edited in the Visual Studio Designer. On the top level a grid with two columns:
   Left a button from WinUI 3.0
   Right a panel with a D3D12 display viewport in it.
2. Upon start the D3D12 display shows the triangle from the current D3D12 hello triangle demo.
3. Upon button press the triangle changes color
4. On the D3D12 display is a toolstrip with button (with an icon being a triangle over a transparent background) that upon press also changes the triangle color.
5. Right click anywhere on the D3D12 display brings up a context menu with one entry to change color.
6. Left mouse drag on the D3D12 display rotates or zooms the triangle.
7. Be a model of best practices, so include the fence demo setup from D3D12HelloFrameBuffering
8. A second button that triggers creating a simple checkerboard image in C# and then sending it to D3D12 as texture for the triangle as an example how to move memory from the CPU to the GPU.

IUnknown does not have a [NativeTypeName] attribute

I don't need this but it seems odd

SHELLEXECUTEINFOW size is wrong on x64/arm64

The size of this struct is supposed to be 112, but it's defined with Pack=1 and ends up with a size of 104 on x64 (and probably arm64). This is preventing ShellExecuteExW() from working, it just returns ERROR_ACCESS_DENIED.

Add attributes to document COM interface inheritance

We've talked about this on Discord, but having an issue will make this easier to track.

COM interfaces have inheritance relationships, e.g. ID2D1SolidColorBrush inherits from ID2D1Brush, then ID2D1Resource, then IUnknown. In native code you can pass an ID2D1SolidColorBrush* to a method that takes an ID2D1Brush* and it works fine. With C# / TerraFX, you have to cast the pointer every time you do this. The cast is safe, but the compiler can't verify that, and you can easily do the wrong thing such as casting ID2D1Bitmap* to ID2D1Brush*. It'll crash spectacularly at runtime, but nothing at compile-time.

Making this work in TerraFX would be an uphill battle since C# doesn't have any way of making this work, other than maybe auto-generating e.g. struct PIUnknown { IUnknown *p; } wrappers for every interface along with the proper cast operators. And then all your code has to use these in place of pointers, but also needs to use the real pointers at ABI boundaries.

TerraFX doesn't need to include these wrappers and the casting operators, but I could generate them on my own for my own project. However, I can't do that without the inheritance information, which doesn't exist.

So, something like this would be nice in TerraFX:

[NativeInheritance(typeof(ID2D1Brush))]
public struct ID2D1SolidColorBrush
{
    ...
}

Then I can experiment with code-genning my own solutions to this. Anything easily accessible via standard reflection should work.

Some interfaces have multiple interfaces they derive from. Those can be handled by using additional [NativeInheritance(...)]'s.

[NativeInheritance(typeof(IBaseInterface1))]
[NativeInheritance(typeof(IBaseInterface2))]
public struct IMultipleInheritance
    // : IBaseInterface1, IBaseInterface2
{
    ...
}

I'd prefer typeof over strings, e.g. [NativeInheritance("ID2D1Brush")]

Newer DWMWINDOWATTRIBUTE / DWMA_ values are missing

Looks like DWMWA_USE_IMMERSIVE_DARK_MODE and a few others are now in the headers and listed in the docs page https://docs.microsoft.com/en-us/windows/win32/api/dwmapi/ne-dwmapi-dwmwindowattribute, although they lack descriptions

typedef enum DWMWINDOWATTRIBUTE {
  DWMWA_NCRENDERING_ENABLED,
  DWMWA_NCRENDERING_POLICY,
  DWMWA_TRANSITIONS_FORCEDISABLED,
  DWMWA_ALLOW_NCPAINT,
  DWMWA_CAPTION_BUTTON_BOUNDS,
  DWMWA_NONCLIENT_RTL_LAYOUT,
  DWMWA_FORCE_ICONIC_REPRESENTATION,
  DWMWA_FLIP3D_POLICY,
  DWMWA_EXTENDED_FRAME_BOUNDS,
  DWMWA_HAS_ICONIC_BITMAP,
  DWMWA_DISALLOW_PEEK,
  DWMWA_EXCLUDED_FROM_PEEK,
  DWMWA_CLOAK,
  DWMWA_CLOAKED,
  DWMWA_FREEZE_REPRESENTATION,
  DWMWA_PASSIVE_UPDATE_MODE,
  DWMWA_USE_HOSTBACKDROPBRUSH,
  DWMWA_USE_IMMERSIVE_DARK_MODE,
  DWMWA_WINDOW_CORNER_PREFERENCE,
  DWMWA_BORDER_COLOR,
  DWMWA_CAPTION_COLOR,
  DWMWA_TEXT_COLOR,
  DWMWA_VISIBLE_FRAME_BORDER_THICKNESS,
  DWMWA_LAST
} ;

VariantInit() and friends are missing

https://docs.microsoft.com/en-us/windows/win32/api/oleauto/nf-oleauto-variantinit

I just started my first conversion from a C++/CLI wrapper to a C# one, and immediately bumped into things like VariantInit() being missing.

Also, VARIANT.vt and PROPVARIANT.vt should be a VARTYPE or VARENUM instead of ushort.

It looks like my VARIANT code mostly works by reinterpret-casting to PROPVARIANT and doing its work, so I'll update this issue if I see any missing Prop*() methods.

Investigate using non-strongly typed VTBLs

@jkotas suggested here that using non-strongly typed VTBLs might be beneficial for IL Linking.

The type definitions currently look like this: https://github.com/terrafx/terrafx.interop.windows/blob/master/sources/Interop/Windows/um/Unknwnbase/IUnknown.cs

Such a modification might look like:

using System;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;

namespace TerraFX.Interop
{
    [Guid("00000000-0000-0000-C000-000000000046")]
    public unsafe partial struct IUnknown
    {
        public void** lpVtbl;

        [return: NativeTypeName("HRESULT")]
        public int QueryInterface([NativeTypeName("const IID &")] Guid* riid, [NativeTypeName("void **")] void** ppvObject)
        {
            return ((delegate* stdcall<IUnknown*, Guid*, void**, int>)(lpVtbl[0]))((IUnknown*)Unsafe.AsPointer(ref this), riid, ppvObject);
        }

        [return: NativeTypeName("ULONG")]
        public uint AddRef()
        {
            return ((delegate* stdcall<IUnknown*, uint>)(lpVtbl[1]))((IUnknown*)Unsafe.AsPointer(ref this));
        }

        [return: NativeTypeName("ULONG")]
        public uint Release()
        {
            var release = ((delegate* stdcall<IUnknown*, uint>)(lpVtbl[2]));
            return release((IUnknown*)Unsafe.AsPointer(ref this));
        }
    }
}

Some HANDLE related things

I'm running across a few things that might have been missed or could be improved:

• BeginBufferedAnimation is documented as returning HANIMATIONBUFFER , but in TerraFX it returns HANDLE https://docs.microsoft.com/en-us/windows/win32/api/uxtheme/nf-uxtheme-beginbufferedanimation

I'll add more replies as I run into more of these :)

Missing UxTheme APIs

OpenThemeDataEx
https://docs.microsoft.com/en-us/windows/win32/api/uxtheme/nf-uxtheme-openthemedataex

OpenThemeDataForDpi
I see this in the uxtheme.h header file, but I don't see a docs page for it

^ Looks like those consts are missing too

There could be others, I just spotted these while wrestling with some button rendering stuff

Need support for psapi.dll

psapi.dll is nowhere to be seen in TerraFX

This is needed for e.g. EnumProcessModulesEx https://docs.microsoft.com/en-us/windows/win32/api/psapi/nf-psapi-enumprocessmodulesex (which I use in Paint.NET)

NativeInheritance attributes with missing/incorrect base types

Found these while experimenting with a generator for the PUnknown wrappers I was talking about on Discord.

The assumption is that [NativeInheritance("FOO")] means that a TerraFx.Interop.FOO entity exists, retrievable via assembly.GetType("TerraFX.Interop.FOO"). For these, that's not true:

Missing base type IDispatchEx for IIE70DispatchEx
Missing base type IDispatchEx for IIE80DispatchEx
Missing base type tagBIND_OPTS for BIND_OPTS2
Missing base type tagBIND_OPTS2 for BIND_OPTS3
Missing base type tagMONITORINFO for MONITORINFOEXA
Missing base type tagMONITORINFO for MONITORINFOEXW
Missing base type tagMOUSEHOOKSTRUCT for MOUSEHOOKSTRUCTEX

This doesn't block me, I can just skip them for now. Could be a useful unit test though.

Consider adding SizeOf property to all structs

May not be a good idea, but worth considering.

There's a bug hazard right now in that the 'helper' structs which are unions of the 32-bit and 64-bit variants have a SizeOf property. You need to know / remember when to use T.SizeOf vs. Unsafe.SizeOf<T>(), and if you incorrectly use the latter then you can get into trouble. It is not something that stands out as incorrect while doing a code review.

One possible solution is to put SizeOf on all structs and have it be the de facto way of determining the struct's size.

[IDEA] Add samples for Windows.UI.Composition

Windows.UI.Composition is a library that exposes the API for the system's composition engine. It provides support for creating, animating, and applying effects to visual elements. This issue suggests adding a couple of samples to demonstrate use of the native Composition interop APIs, which allow support for drawing to Win32 HWNDs and DirectX interop.

Add safe string methods (StringCch*)

I think this is a header-only lib, so it would need to be implemented manually?

I'm not currently using these from managed code, but would still be useful for converting some native code at some point. Not a high priority for me at this time.

Add BSTR and related methods (e.g. SysAllocString*)

This would enable more code to be converted away from System.Runtime.InteropServices.Marshal, which has kind of an unmodern icky .NET 1.0 feel to it. It would help usage of TerraFX.Interop.Windows to be more self-contained.

Missing PixelFormat Guid

GUID_WICPixelFormat16bppBGRA555 is missing

I see...

GUID_WICPixelFormat16bppBGRA5551

which is not a format identifier.

Add the errhandlingapi.h methods (SetErrorMode, etc)

I am in the process of converting a .NET 6 project to use TerraFx, and SetErrorMode is the only missing method that I use.

STGM_* constants are missing

The STGM_* contants (https://docs.microsoft.com/en-us/windows/win32/stg/stgm-constants) don't appear to be available in TerraFX.Interop.Windows. I ran into this while implementing IStream.Stat, since the STATSTG type uses those constants for its grfMode field.

Consider exposing some sort of ThrowIfFailed(HRESULT) method

Proposals

One such is already exposed in HelperUtilities, although this is an internal utility type. Would be very useful for code which uses lower-level portions of the library where checking HRESULTs is a regular occurence

Win32 Shell APIs are not present

I was looking into using IKnownFolderManager and/or SHGetKnownFolderPath, but as far as I can tell all Win32 Shell APIs are missing

https://docs.microsoft.com/en-us/windows/win32/shell/known-folders

https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nn-shobjidl_core-iknownfoldermanager

https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nn-shobjidl_core-iknownfolder

https://docs.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetknownfolderpath

BufferedPaintMakeOpaque should return HRESULT

It's a macro around BufferedPaintSetAlpha, which returns HRESULT. Easy to miss. https://docs.microsoft.com/en-us/windows/win32/api/uxtheme/nf-uxtheme-bufferedpaintsetalpha

The BufferedPaintMakeOpaque macro, which is defined in uxtheme.h, sets alpha values to 255. It is typically used to call GDI to draw into a memory buffer and then to make it opaque in order to draw it on glass.

The documents lack instructions about how to consume the bindings

At least there should be a couple lines that tell you which NuGet feed one should add!

Remove interop namespace

Just a suggestion, remove interop from namespaces. It's not needed.

SetLastError = true missing from at least a few important methods

CreateFileMappingW, for one

Also, it looks like both GetLastError and SetLastError are missing, although I would expect folks to use Marshal.GetLastWin32Error(). However, it seems unintentional that these are missing since they don't show up when searching the repository (I'd expect a filter or something? I'm not sure how all this works though.)

Add bindings for native GDI+

Most of GDI+ is already available in System.Drawing, but there are a few things in GDI+ 1.1 that aren't. Namely, the effects API in gdipluseffects.h. I use the red-eye correction effect (Gdiplus::RedEyeCorrection) in Paint.NET, and it'd be nice to move that block of code out of C and into C#.

This is a nice-to-have and not a high priority, especially since it requires handling a bunch of C++ header files.

[PROPOSAL] Add bindings for DirectXTex

Description (optional)

Add bindings for DirectXTex https://github.com/microsoft/DirectXTex/blob/master/DirectXTex/DirectXTex.h

Rationale

DirectXTex is a library for reading and writing DDS files and perform other operations on such texture files.

Some more missing constants and methods

Instead of filing 1 issue per thing I find, I'll keep a "blog" of sorts here. Let me know if you prefer otherwise.

Resolved with #205

• I don't see the SHTDN_REASON_* constants, e.g.

        public const uint SHTDN_REASON_FLAG_COMMENT_REQUIRED = 0x01000000;
        public const uint SHTDN_REASON_FLAG_DIRTY_PROBLEM_ID_REQUIRED = 0x02000000;
        public const uint SHTDN_REASON_FLAG_CLEAN_UI = 0x04000000;
        public const uint SHTDN_REASON_FLAG_DIRTY_UI = 0x08000000;
        public const uint SHTDN_REASON_FLAG_USER_DEFINED = 0x40000000;
        public const uint SHTDN_REASON_FLAG_PLANNED = 0x80000000;

        public const uint SHTDN_REASON_MAJOR_OTHER = 0x00000000;
        public const uint SHTDN_REASON_MAJOR_NONE = 0x00000000;
        public const uint SHTDN_REASON_MAJOR_HARDWARE = 0x00010000;
        public const uint SHTDN_REASON_MAJOR_OPERATINGSYSTEM = 0x00020000;
        public const uint SHTDN_REASON_MAJOR_SOFTWARE = 0x00030000;
        public const uint SHTDN_REASON_MAJOR_APPLICATION = 0x00040000;
        public const uint SHTDN_REASON_MAJOR_SYSTEM = 0x00050000;
        public const uint SHTDN_REASON_MAJOR_POWER = 0x00060000;
        public const uint SHTDN_REASON_MAJOR_LEGACY_API = 0x00070000;

        public const uint SHTDN_REASON_MINOR_OTHER = 0x00000000;
        public const uint SHTDN_REASON_MINOR_NONE = 0x000000ff;
        public const uint SHTDN_REASON_MINOR_MAINTENANCE = 0x00000001;
        public const uint SHTDN_REASON_MINOR_INSTALLATION = 0x00000002;
        public const uint SHTDN_REASON_MINOR_UPGRADE = 0x00000003;
        public const uint SHTDN_REASON_MINOR_RECONFIG = 0x00000004;
        public const uint SHTDN_REASON_MINOR_HUNG = 0x00000005;
        public const uint SHTDN_REASON_MINOR_UNSTABLE = 0x00000006;
        public const uint SHTDN_REASON_MINOR_DISK = 0x00000007;
        public const uint SHTDN_REASON_MINOR_PROCESSOR = 0x00000008;
        public const uint SHTDN_REASON_MINOR_NETWORKCARD = 0x00000009;
        public const uint SHTDN_REASON_MINOR_POWER_SUPPLY = 0x0000000a;
        public const uint SHTDN_REASON_MINOR_CORDUNPLUGGED = 0x0000000b;
        public const uint SHTDN_REASON_MINOR_ENVIRONMENT = 0x0000000c;
        public const uint SHTDN_REASON_MINOR_HARDWARE_DRIVER = 0x0000000d;
        public const uint SHTDN_REASON_MINOR_OTHERDRIVER = 0x0000000e;
        public const uint SHTDN_REASON_MINOR_BLUESCREEN = 0x0000000F;
        public const uint SHTDN_REASON_MINOR_SERVICEPACK = 0x00000010;
        public const uint SHTDN_REASON_MINOR_HOTFIX = 0x00000011;
        public const uint SHTDN_REASON_MINOR_SECURITYFIX = 0x00000012;
        public const uint SHTDN_REASON_MINOR_SECURITY = 0x00000013;
        public const uint SHTDN_REASON_MINOR_NETWORK_CONNECTIVITY = 0x00000014;
        public const uint SHTDN_REASON_MINOR_WMI = 0x00000015;
        public const uint SHTDN_REASON_MINOR_SERVICEPACK_UNINSTALL = 0x00000016;
        public const uint SHTDN_REASON_MINOR_HOTFIX_UNINSTALL = 0x00000017;
        public const uint SHTDN_REASON_MINOR_SECURITYFIX_UNINSTALL = 0x00000018;
        public const uint SHTDN_REASON_MINOR_MMC = 0x00000019;
        public const uint SHTDN_REASON_MINOR_SYSTEMRESTORE = 0x0000001a;
        public const uint SHTDN_REASON_MINOR_TERMSRV = 0x00000020;
        public const uint SHTDN_REASON_MINOR_DC_PROMOTION = 0x00000021;
        public const uint SHTDN_REASON_MINOR_DC_DEMOTION = 0x00000022;
        public const uint SHTDN_REASON_UNKNOWN = SHTDN_REASON_MINOR_NONE;
        public const uint SHTDN_REASON_LEGACY_API = (SHTDN_REASON_MAJOR_LEGACY_API | SHTDN_REASON_FLAG_PLANNED);
        public const uint SHTDN_REASON_VALID_BIT_MASK = 0xc0ffffff;

Expose DbgHelp.h

https://docs.microsoft.com/en-us/windows/win32/debug/debug-help-library
Comprised of DbgHelp.h and minidumpapiset.h. Also requires exposing verrsrc.h and timezoneapi.h.