Deprecate the old C API

[tangent-vector]

The Slang API has evolved over a long period of time, stretching back to well before the system was even called "Slang." The C API of sp-prefixed functions no longer reflects the intended way to use Slang, and we would like to deprecate (and eventually remove) these functions so that we no longer have to maintain them as we introduce new functionality.

Issue #3616 covers the more urgent task of discouraging new users from writing code using the to-be-deprecated API.

Further steps to effectively deprecate and remove the C API should ideally include:

• Ensure that the COM/C++ API is feature-complete for all use cases that the C API currently covers

• Refactor the slang.h API header so that the C++ API is declared first, and the C API types are expressed as typedefs of the C++ types, instead of the other way around. This step should not break binary compatibility but may break source compatibility in narrow cases (e.g., if client code forward-declares Slang API types, the distinction between something being a struct vs. a typedef is visible).

• Split the C API out of the primary slang.h header, so that anybody reading the header only sees the C++ API, and can clearly see something like #if SLANG_LEGACY_API_ENABLED or similar guarding an include of something like slang-legacy-api.h

• Move the implementation of the C API (in terms of the C++ API) from the Slang implementation itself into the slang-legacy-api.h header, so that it is effectively a single-file library wrapping the proper Slang API. This step should be binary-breaking but not source-breaking for clients using the old API.

• Make the legacy API be disabled by default, so that client code must opt into it.

• Add deprecation warnings that will trigger for code that opts into the C API (easy enough to do with a #pragma warning

• Remove the C API while keeping the relevant #define/#include enable, by switching the #pragma warning to a #error.

• Remove the support cruft entirely.

The above steps can be staged out slowly, or lumped together into a smaller number of changes, depending on how quickly we think we can migrate existing users over to the new API.

[laurooyen]

It's unfortunate to see the C API go since it allowed me to automatically generate Rust language bindings to Slang for use in my own open-source toy engine. I fully understand the decision to deprecate though.

EDIT: Assuming the slang_createGlobalSession dll export won't be deprecated, I created new Rust bindings based on the COM API. If anyone is interested, they're open source and available here: https://github.com/FloatyMonkey/slang-rs.

The biggest missing part of the COM API and therefore my new bindings is reflection. It is available in the C++ API but not as a COM Interface so generating bindings to it is not possible.

[csyonghe]

Blocked by #3882.

[csyonghe]

@laurooyen We will keep the reflection API as is and there is no plan to deprecate them.

[csyonghe]

The functions to deprecate are all the sp* functions, plus the ICompileRequest interface.

[milliewalky]

Given these:

1. Refactoring the slang.h API header so that the C++ API is declared first, and the C API types are expressed as typedefs of the C++ types.
2. Moving the implementation of the C API (in terms of the C++ API) into the slang-legacy-api.h header, making it a single-file library wrapping the proper Slang API.

Could you further clarify if the intention is to provide C bindings to the C++ API, or if there's another direction planned for supporting C users?

[csyonghe]

For the C API, we will need to use some code generators to generate C wrappers from the COM interface, so that we don't need to maintain the two versions manually. We haven't planned this work yet but it is something we will need before removing the existing C API.

[milliewalky]

This is excellent, thank you!