diff --git a/gen/cheader.tmpl b/gen/cheader.tmpl index 6adc541e..34263ea4 100644 --- a/gen/cheader.tmpl +++ b/gen/cheader.tmpl @@ -65,6 +65,21 @@ #include "webgpu.h" {{end}} +{{- if eq .Name "webgpu"}} +#define WGPU_COMMA , +#if defined(__cplusplus) +# if __cplusplus >= 201103L +# define WGPU_MAKE_INIT_STRUCT(type, value) (type value) +# else +# define WGPU_MAKE_INIT_STRUCT(type, value) value +# endif +#elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L +# define WGPU_MAKE_INIT_STRUCT(type, value) ((type) value) +#else +# define WGPU_MAKE_INIT_STRUCT(type, value) value +#endif +{{end}} + /** * \defgroup Constants * \brief Constants. @@ -221,6 +236,37 @@ typedef struct WGPUChainedStructOut { * @{ */ +/** + * Nullable value defining a pointer+length view into a UTF-8 encoded string. + * + * Values passed into the API may use the special length value @ref WGPU_STRLEN + * to indicate a null-terminated string. + * Non-null values passed out of the API (for example as callback arguments) + * always provide an explicit length and **may or may not be null-terminated**. + * + * Some inputs to the API accept null values. Those which do not accept null + * values "default" to the empty string when null values are passed. + * + * Values are encoded as follows: + * - `{NULL, WGPU_STRLEN}`: the null value. + * - `{non_null_pointer, WGPU_STRLEN}`: a null-terminated string view. + * - `{any, 0}`: the empty string. + * - `{NULL, non_zero_length}`: not allowed (null dereference). + * - `{non_null_pointer, non_zero_length}`: an explictly-sized string view. + * + * To format explicitly-sized strings with `printf`, use `%.*s` + * (`%s` with a "precision" argument `.*` specifying a max length). + */ +typedef struct WGPUStringView { + char const * WGPU_NULLABLE data; + size_t length; +} WGPUStringView; + +#define WGPU_STRING_VIEW_INIT WGPU_MAKE_INIT_STRUCT(WGPUStringView, { \ + /*.data=*/NULL WGPU_COMMA \ + /*.length=*/WGPU_STRLEN WGPU_COMMA \ +}) + /** * \defgroup WGPUCallbackInfo * \brief Callback info structures that are used in asynchronous functions. diff --git a/webgpu.h b/webgpu.h index 9f790d83..27418f83 100644 --- a/webgpu.h +++ b/webgpu.h @@ -55,6 +55,19 @@ #include #include +#define WGPU_COMMA , +#if defined(__cplusplus) +# if __cplusplus >= 201103L +# define WGPU_MAKE_INIT_STRUCT(type, value) (type value) +# else +# define WGPU_MAKE_INIT_STRUCT(type, value) value +# endif +#elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L +# define WGPU_MAKE_INIT_STRUCT(type, value) ((type) value) +#else +# define WGPU_MAKE_INIT_STRUCT(type, value) value +#endif + /** * \defgroup Constants @@ -998,6 +1011,37 @@ typedef struct WGPUChainedStructOut { * @{ */ +/** + * Nullable value defining a pointer+length view into a UTF-8 encoded string. + * + * Values passed into the API may use the special length value @ref WGPU_STRLEN + * to indicate a null-terminated string. + * Non-null values passed out of the API (for example as callback arguments) + * always provide an explicit length and **may or may not be null-terminated**. + * + * Some inputs to the API accept null values. Those which do not accept null + * values "default" to the empty string when null values are passed. + * + * Values are encoded as follows: + * - `{NULL, WGPU_STRLEN}`: the null value. + * - `{non_null_pointer, WGPU_STRLEN}`: a null-terminated string view. + * - `{any, 0}`: the empty string. + * - `{NULL, non_zero_length}`: not allowed (null dereference). + * - `{non_null_pointer, non_zero_length}`: an explictly-sized string view. + * + * To format explicitly-sized strings with `printf`, use `%.*s` + * (`%s` with a "precision" argument `.*` specifying a max length). + */ +typedef struct WGPUStringView { + char const * WGPU_NULLABLE data; + size_t length; +} WGPUStringView; + +#define WGPU_STRING_VIEW_INIT WGPU_MAKE_INIT_STRUCT(WGPUStringView, { \ + /*.data=*/NULL WGPU_COMMA \ + /*.length=*/WGPU_STRLEN WGPU_COMMA \ +}) + /** * \defgroup WGPUCallbackInfo * \brief Callback info structures that are used in asynchronous functions.