From 7329d15bfd80d5b94ca061f54daef1a8a8104e84 Mon Sep 17 00:00:00 2001 From: Kai Ninomiya Date: Wed, 16 Oct 2024 19:38:04 -0400 Subject: [PATCH 1/6] Add docs on ownership Also generate docs for function parameters. --- doc/articles/index.md | 1 + gen/cheader.tmpl | 8 ++-- gen/gen.go | 78 ++++++++++++++++++++++++++++------ gen/yml.go | 47 +++++++++++---------- schema.json | 36 +++++++++++++++- webgpu.h | 98 +++++++++++++++++++++++++++++++++++++++++-- webgpu.yml | 43 ++++++++++++++++++- 7 files changed, 265 insertions(+), 46 deletions(-) diff --git a/doc/articles/index.md b/doc/articles/index.md index 8bee45ba..ecf192ca 100644 --- a/doc/articles/index.md +++ b/doc/articles/index.md @@ -1,6 +1,7 @@ \page articles Articles - \subpage Asynchronous-Operations +- \subpage Ownership - \subpage Surfaces - \subpage SentinelValues - \subpage Strings diff --git a/gen/cheader.tmpl b/gen/cheader.tmpl index bb0465d7..472eaec9 100644 --- a/gen/cheader.tmpl +++ b/gen/cheader.tmpl @@ -242,7 +242,7 @@ typedef void (*WGPUProc)(void) WGPU_FUNCTION_ATTRIBUTE; */ {{- range .Callbacks}} -{{- MComment .Doc 0}} +{{- MCommentCallback . 0}} typedef void (*WGPU{{.Name | PascalCase}}Callback{{$.ExtSuffix}})({{CallbackArgs .}}) WGPU_FUNCTION_ATTRIBUTE; {{- end}} @@ -312,7 +312,7 @@ typedef struct WGPU{{.Name | PascalCase}}{{$.ExtSuffix}} { WGPUChainedStructOut chain; {{- end}} {{- range $memberIndex, $_ := .Members}} - {{- MCommentWithTypeInfo .Doc .Type 4 }} + {{- MCommentMember . 4 }} {{ StructMember $struct $memberIndex}} {{- end}} } WGPU{{.Name | PascalCase}}{{$.ExtSuffix}} WGPU_STRUCTURE_ATTRIBUTE; @@ -376,7 +376,7 @@ typedef void (*WGPUProc{{.Name | PascalCase}}Release{{$.ExtSuffix}})(WGPU{{.Name */ {{- range .Functions}} -{{- MCommentFunction .Doc 0 .Returns}} +{{- MCommentFunction . 0}} WGPU_EXPORT {{FunctionReturns .}} wgpu{{.Name | PascalCase}}{{$.ExtSuffix}}({{FunctionArgs . nil}}) WGPU_FUNCTION_ATTRIBUTE; {{- end}} {{- if eq .Name "webgpu"}} @@ -405,7 +405,7 @@ WGPU_EXPORT WGPUProc wgpuGetProcAddress(WGPUStringView procName) WGPU_FUNCTION_A * @{ */ {{- range $object.Methods}} -{{- MCommentFunction .Doc 0 .Returns}} +{{- MCommentFunction . 0}} WGPU_EXPORT {{FunctionReturns .}} wgpu{{$object.Name | PascalCase}}{{.Name | PascalCase}}{{$.ExtSuffix}}({{FunctionArgs . $object}}) WGPU_FUNCTION_ATTRIBUTE; {{- end}} {{- if not (or .IsStruct .Extended)}} diff --git a/gen/gen.go b/gen/gen.go index f7310334..f311b256 100644 --- a/gen/gen.go +++ b/gen/gen.go @@ -38,37 +38,91 @@ func (g *Generator) Gen(dst io.Writer) error { value, _ := g.BitflagValue(b, entryIndex) return Comment("`"+value+"`.\n"+v, CommentTypeMultiLine, indent, true) }, - "MCommentFunction": func(funcDoc string, indent int, returns *ParameterType) string { + "MCommentFunction": func(fn *Function, indent int) string { var s string - funcDoc = strings.TrimSpace(funcDoc) - if funcDoc != "" && funcDoc != "TODO" { - s += funcDoc + { + var funcDoc = strings.TrimSpace(fn.Doc) + if funcDoc != "" && funcDoc != "TODO" { + s += funcDoc + } } - if returns != nil { - returnsDoc := strings.TrimSpace(returns.Doc) + for _, arg := range fn.Args { + var argDoc = strings.TrimSpace(arg.Doc) + var sArg string + if argDoc != "" && argDoc != "TODO" { + sArg += argDoc + } + + switch arg.OwnershipDoc { + case "with": + sArg += "\nThis parameter is @ref ReturnedWithOwnership." + case "without": + panic("invalid") + } + + sArg = strings.TrimSpace(sArg) + if sArg != "" { + s += "\n\n@param " + arg.Name + "\n" + sArg + } + } + if fn.Returns != nil { + returnsDoc := strings.TrimSpace(fn.Returns.Doc) if returnsDoc != "" && returnsDoc != "TODO" { - s += "\n\n@returns " + returnsDoc + s += "\n\n@returns\n\n" + returnsDoc + } + } + return Comment(strings.TrimSpace(s), CommentTypeMultiLine, indent, true) + }, + "MCommentCallback": func(cb *Callback, indent int) string { + var s string + { + var funcDoc = strings.TrimSpace(cb.Doc) + if funcDoc != "" && funcDoc != "TODO" { + s += funcDoc + } + } + for _, arg := range cb.Args { + var argDoc = strings.TrimSpace(arg.Doc) + var sArg string + if argDoc != "" && argDoc != "TODO" { + sArg += argDoc + } + + switch arg.OwnershipDoc { + case "with": + sArg += "\nThis parameter is @ref PassedWithOwnership." + case "without": + sArg += "\nThis parameter is @ref PassedWithoutOwnership." + } + + sArg = strings.TrimSpace(sArg) + if sArg != "" { + s += "\n\n@param " + arg.Name + "\n" + sArg } } return Comment(strings.TrimSpace(s), CommentTypeMultiLine, indent, true) }, - "MCommentWithTypeInfo": func(srcDoc string, typ string, indent int) string { + "MCommentMember": func(member *ParameterType, indent int) string { var s string - srcDoc = strings.TrimSpace(srcDoc) + + var srcDoc = strings.TrimSpace(member.Doc) if srcDoc != "" && srcDoc != "TODO" { s += srcDoc } - switch typ { + switch member.Type { case "nullable_string": s += "\n\nThis is a \\ref NullableInputString." case "string_with_default_empty": s += "\n\nThis is a \\ref NonNullInputString." case "out_string": s += "\n\nThis is an \\ref OutputString." - default: - s += "" } + + if member.OwnershipDoc != "" { + panic("invalid") + } + return Comment(strings.TrimSpace(s), CommentTypeMultiLine, indent, true) }, "ConstantCase": ConstantCase, diff --git a/gen/yml.go b/gen/yml.go index a36049a2..704f62fa 100644 --- a/gen/yml.go +++ b/gen/yml.go @@ -12,14 +12,14 @@ type Yml struct { Name string `yaml:"name"` EnumPrefix string `yaml:"enum_prefix"` - Constants []Constant `yaml:"constants"` - Typedefs []Typedef `yaml:"typedefs"` - Enums []Enum `yaml:"enums"` - Bitflags []Bitflag `yaml:"bitflags"` - Structs []Struct `yaml:"structs"` - Callbacks []Callback `yaml:"callbacks"` - Functions []Function `yaml:"functions"` - Objects []Object `yaml:"objects"` + Constants []Constant `yaml:"constants"` + Typedefs []Typedef `yaml:"typedefs"` + Enums []Enum `yaml:"enums"` + Bitflags []Bitflag `yaml:"bitflags"` + Structs []Struct `yaml:"structs"` + Callbacks []Callback `yaml:"callbacks"` + Functions []Function `yaml:"functions"` + Objects []Object `yaml:"objects"` } type Constant struct { @@ -67,27 +67,28 @@ const ( ) type ParameterType struct { - Name string `yaml:"name"` - Doc string `yaml:"doc"` - Type string `yaml:"type"` - Pointer PointerType `yaml:"pointer"` - Optional bool `yaml:"optional"` - Namespace string `yaml:"namespace"` + Name string `yaml:"name"` + Doc string `yaml:"doc"` + Type string `yaml:"type"` + OwnershipDoc string `yaml:"ownership_doc"` + Pointer PointerType `yaml:"pointer"` + Optional bool `yaml:"optional"` + Namespace string `yaml:"namespace"` } type Callback struct { - Name string `yaml:"name"` - Doc string `yaml:"doc"` - Style string `yaml:"type"` - Args []ParameterType `yaml:"args"` + Name string `yaml:"name"` + Doc string `yaml:"doc"` + Style string `yaml:"type"` + Args []ParameterType `yaml:"args"` } type Function struct { - Name string `yaml:"name"` - Doc string `yaml:"doc"` - Returns *ParameterType `yaml:"returns"` - Callback *string `yaml:"callback"` - Args []ParameterType `yaml:"args"` + Name string `yaml:"name"` + Doc string `yaml:"doc"` + Returns *ParameterType `yaml:"returns"` + Callback *string `yaml:"callback"` + Args []ParameterType `yaml:"args"` } type Struct struct { diff --git a/schema.json b/schema.json index 80936cd1..62dba096 100644 --- a/schema.json +++ b/schema.json @@ -109,7 +109,7 @@ "type": "array", "description": "Optional property, list of callback arguments", "items": { - "$ref": "#/definitions/ParameterType" + "$ref": "#/definitions/FunctionParameterType" } } }, @@ -133,6 +133,14 @@ "$ref": "#/definitions/Type", "description": "Parameter type" }, + "ownership": { + "type": "string", + "description": "Ownership of the value", + "enum": [ + "with", + "without" + ] + }, "pointer": { "$ref": "#/definitions/Pointer", "description": "Optional property, specifies if a parameter type is a pointer" @@ -153,6 +161,23 @@ "type" ] }, + "FunctionParameterType": { + "allOf": [ + { + "$ref": "#/definitions/ParameterType" + }, + { + "type": "object", + "properties": { + "doc": { + "type": "string", + "$comment": "Doxygen doesn't support multi-paragraph param docs (containing \\n\\n)", + "pattern": "^\n?.+(\n.+)*\n?$" + } + } + } + ] + }, "Function": { "type": "object", "properties": { @@ -174,6 +199,13 @@ "$ref": "#/definitions/Type", "description": "Return type of the function" }, + "ownership": { + "type": "string", + "description": "Ownership of the value", + "enum": [ + "with" + ] + }, "pointer": { "$ref": "#/definitions/Pointer", "description": "Optional property, specifies if a method return type is a pointer" @@ -192,7 +224,7 @@ "type": "array", "description": "Optional property, list of function arguments", "items": { - "$ref": "#/definitions/ParameterType" + "$ref": "#/definitions/FunctionParameterType" } } }, diff --git a/webgpu.h b/webgpu.h index 8272d032..fea80b3e 100644 --- a/webgpu.h +++ b/webgpu.h @@ -1153,15 +1153,63 @@ typedef void (*WGPUProc)(void) WGPU_FUNCTION_ATTRIBUTE; * * @{ */ +/** + * @param message + * This parameter is @ref PassedWithoutOwnership. + */ typedef void (*WGPUBufferMapCallback)(WGPUMapAsyncStatus status, WGPUStringView message, WGPU_NULLABLE void* userdata1, WGPU_NULLABLE void* userdata2) WGPU_FUNCTION_ATTRIBUTE; +/** + * @param compilation_info + * This parameter is @ref PassedWithoutOwnership. + */ typedef void (*WGPUCompilationInfoCallback)(WGPUCompilationInfoRequestStatus status, struct WGPUCompilationInfo const * compilationInfo, WGPU_NULLABLE void* userdata1, WGPU_NULLABLE void* userdata2) WGPU_FUNCTION_ATTRIBUTE; +/** + * @param pipeline + * This parameter is @ref PassedWithOwnership. + */ typedef void (*WGPUCreateComputePipelineAsyncCallback)(WGPUCreatePipelineAsyncStatus status, WGPUComputePipeline pipeline, WGPUStringView message, WGPU_NULLABLE void* userdata1, WGPU_NULLABLE void* userdata2) WGPU_FUNCTION_ATTRIBUTE; +/** + * @param pipeline + * This parameter is @ref PassedWithOwnership. + */ typedef void (*WGPUCreateRenderPipelineAsyncCallback)(WGPUCreatePipelineAsyncStatus status, WGPURenderPipeline pipeline, WGPUStringView message, WGPU_NULLABLE void* userdata1, WGPU_NULLABLE void* userdata2) WGPU_FUNCTION_ATTRIBUTE; +/** + * @param device + * This parameter is @ref PassedWithoutOwnership. + * + * @param message + * This parameter is @ref PassedWithoutOwnership. + */ typedef void (*WGPUDeviceLostCallback)(WGPUDevice const * device, WGPUDeviceLostReason reason, WGPUStringView message, WGPU_NULLABLE void* userdata1, WGPU_NULLABLE void* userdata2) WGPU_FUNCTION_ATTRIBUTE; +/** + * @param message + * This parameter is @ref PassedWithoutOwnership. + */ typedef void (*WGPUPopErrorScopeCallback)(WGPUPopErrorScopeStatus status, WGPUErrorType type, WGPUStringView message, WGPU_NULLABLE void* userdata1, WGPU_NULLABLE void* userdata2) WGPU_FUNCTION_ATTRIBUTE; typedef void (*WGPUQueueWorkDoneCallback)(WGPUQueueWorkDoneStatus status, WGPU_NULLABLE void* userdata1, WGPU_NULLABLE void* userdata2) WGPU_FUNCTION_ATTRIBUTE; +/** + * @param adapter + * This parameter is @ref PassedWithOwnership. + * + * @param message + * This parameter is @ref PassedWithoutOwnership. + */ typedef void (*WGPURequestAdapterCallback)(WGPURequestAdapterStatus status, WGPUAdapter adapter, WGPUStringView message, WGPU_NULLABLE void* userdata1, WGPU_NULLABLE void* userdata2) WGPU_FUNCTION_ATTRIBUTE; +/** + * @param device + * This parameter is @ref PassedWithOwnership. + * + * @param message + * This parameter is @ref PassedWithoutOwnership. + */ typedef void (*WGPURequestDeviceCallback)(WGPURequestDeviceStatus status, WGPUDevice device, WGPUStringView message, WGPU_NULLABLE void* userdata1, WGPU_NULLABLE void* userdata2) WGPU_FUNCTION_ATTRIBUTE; +/** + * @param device + * This parameter is @ref PassedWithoutOwnership. + * + * @param message + * This parameter is @ref PassedWithoutOwnership. + */ typedef void (*WGPUUncapturedErrorCallback)(WGPUDevice const * device, WGPUErrorType type, WGPUStringView message, WGPU_NULLABLE void* userdata1, WGPU_NULLABLE void* userdata2) WGPU_FUNCTION_ATTRIBUTE; /** @} */ @@ -1790,6 +1838,7 @@ typedef struct WGPUSurfaceSourceXlibWindow { typedef struct WGPUSurfaceTexture { /** * The @ref WGPUTexture representing the frame that will be shown on the surface. + * It is @ref ReturnedWithOwnership from @ref wgpuSurfaceGetCurrentTexture. */ WGPUTexture texture; /** @@ -3084,6 +3133,9 @@ typedef void (*WGPUProcTextureViewRelease)(WGPUTextureView textureView) WGPU_FUN WGPU_EXPORT WGPUInstance wgpuCreateInstance(WGPU_NULLABLE WGPUInstanceDescriptor const * descriptor) WGPU_FUNCTION_ATTRIBUTE; /** * Query the supported instance features + * + * @param features + * The supported instance features */ WGPU_EXPORT void wgpuGetInstanceFeatures(WGPUInstanceFeatures * features) WGPU_FUNCTION_ATTRIBUTE; /** @@ -3111,11 +3163,20 @@ WGPU_EXPORT WGPUProc wgpuGetProcAddress(WGPUStringView procName) WGPU_FUNCTION_A /** * Get the list of @ref WGPUFeatureName values supported by the adapter. * - * @returns Return @ref WGPUStatus_Error (and leaves `features` uninitialized) if: + * @param features + * This parameter is @ref ReturnedWithOwnership. + * + * @returns + * + * Return @ref WGPUStatus_Error (and leaves `features` uninitialized) if: * * - `features` has an invalid struct chain. */ WGPU_EXPORT WGPUStatus wgpuAdapterGetFeatures(WGPUAdapter adapter, WGPUSupportedFeatures * features) WGPU_FUNCTION_ATTRIBUTE; +/** + * @param info + * This parameter is @ref ReturnedWithOwnership. + */ WGPU_EXPORT void wgpuAdapterGetInfo(WGPUAdapter adapter, WGPUAdapterInfo * info) WGPU_FUNCTION_ATTRIBUTE; WGPU_EXPORT WGPUBool wgpuAdapterGetLimits(WGPUAdapter adapter, WGPUSupportedLimits * limits) WGPU_FUNCTION_ATTRIBUTE; WGPU_EXPORT WGPUBool wgpuAdapterHasFeature(WGPUAdapter adapter, WGPUFeatureName feature) WGPU_FUNCTION_ATTRIBUTE; @@ -3285,7 +3346,12 @@ WGPU_EXPORT void wgpuDeviceDestroy(WGPUDevice device) WGPU_FUNCTION_ATTRIBUTE; /** * Get the list of @ref WGPUFeatureName values supported by the device. * - * @returns Return @ref WGPUStatus_Error (and leaves `features` uninitialized) if: + * @param features + * This parameter is @ref ReturnedWithOwnership. + * + * @returns + * + * Return @ref WGPUStatus_Error (and leaves `features` uninitialized) if: * * - `features` has an invalid struct chain. */ @@ -3311,7 +3377,12 @@ WGPU_EXPORT void wgpuDeviceRelease(WGPUDevice device) WGPU_FUNCTION_ATTRIBUTE; /** * Creates a @ref WGPUSurface, see @ref Surface-Creation for more details. * - * @returns A new @ref WGPUSurface for this descriptor (or an error @ref WGPUSurface). + * @param descriptor + * The description of the @ref WGPUSurface to create. + * + * @returns + * + * A new @ref WGPUSurface for this descriptor (or an error @ref WGPUSurface). */ WGPU_EXPORT WGPUSurface wgpuInstanceCreateSurface(WGPUInstance instance, WGPUSurfaceDescriptor const * descriptor) WGPU_FUNCTION_ATTRIBUTE; WGPU_EXPORT WGPUBool wgpuInstanceHasWGSLLanguageFeature(WGPUInstance instance, WGPUWGSLFeatureName feature) WGPU_FUNCTION_ATTRIBUTE; @@ -3514,18 +3585,34 @@ WGPU_EXPORT void wgpuSupportedFeaturesFreeMembers(WGPUSupportedFeatures supporte /** * Configures parameters for rendering to `surface`. * See @ref Surface-Configuration for more details. + * + * @param config + * The new configuration to use. */ WGPU_EXPORT void wgpuSurfaceConfigure(WGPUSurface surface, WGPUSurfaceConfiguration const * config) WGPU_FUNCTION_ATTRIBUTE; /** * Provides information on how `adapter` is able to use `surface`. * See @ref Surface-Capabilities for more details. * - * @returns TODO make this WGPUStatus instead of a boolean. + * @param adapter + * The @ref WGPUAdapter to get capabilities for presenting to this @ref WGPUSurface. + * + * @param capabilities + * The structure to fill capabilities in. + * It may contain memory allocations so `::wgpuSurfaceCapabilitiesFreeMembers` must be called to avoid memory leaks. + * This parameter is @ref ReturnedWithOwnership. + * + * @returns + * + * TODO make this WGPUStatus instead of a boolean. */ WGPU_EXPORT WGPUBool wgpuSurfaceGetCapabilities(WGPUSurface surface, WGPUAdapter adapter, WGPUSurfaceCapabilities * capabilities) WGPU_FUNCTION_ATTRIBUTE; /** * Returns the @ref WGPUTexture to render to `surface` this frame along with metadata on the frame. * See @ref Surface-Presenting for more details. + * + * @param surface_texture + * The structure to fill the @ref WGPUTexture and metadata in. */ WGPU_EXPORT void wgpuSurfaceGetCurrentTexture(WGPUSurface surface, WGPUSurfaceTexture * surfaceTexture) WGPU_FUNCTION_ATTRIBUTE; /** @@ -3535,6 +3622,9 @@ WGPU_EXPORT void wgpuSurfaceGetCurrentTexture(WGPUSurface surface, WGPUSurfaceTe WGPU_EXPORT void wgpuSurfacePresent(WGPUSurface surface) WGPU_FUNCTION_ATTRIBUTE; /** * Modifies the label used to refer to `surface`. + * + * @param label + * The new label. */ WGPU_EXPORT void wgpuSurfaceSetLabel(WGPUSurface surface, WGPUStringView label) WGPU_FUNCTION_ATTRIBUTE; /** diff --git a/webgpu.yml b/webgpu.yml index 0eb4e48b..702208b4 100644 --- a/webgpu.yml +++ b/webgpu.yml @@ -2820,7 +2820,9 @@ structs: type: standalone members: - name: texture - doc: The @ref WGPUTexture representing the frame that will be shown on the surface. + doc: | + The @ref WGPUTexture representing the frame that will be shown on the surface. + It is @ref ReturnedWithOwnership from @ref wgpuSurfaceGetCurrentTexture. type: object.texture - name: status doc: Whether the call to `::wgpuSurfaceGetCurrentTexture` succeeded and a hint as to why it might not have. @@ -3012,6 +3014,7 @@ callbacks: doc: | TODO type: out_string + ownership_doc: without - name: compilation_info doc: | TODO @@ -3026,6 +3029,7 @@ callbacks: TODO type: struct.compilation_info pointer: immutable + ownership_doc: without - name: create_compute_pipeline_async doc: | TODO @@ -3039,6 +3043,7 @@ callbacks: doc: | TODO type: object.compute_pipeline + ownership_doc: with - name: message doc: | TODO @@ -3056,6 +3061,7 @@ callbacks: doc: | TODO type: object.render_pipeline + ownership_doc: with - name: message doc: | TODO @@ -3069,6 +3075,7 @@ callbacks: TODO type: object.device pointer: immutable + ownership_doc: without - name: reason doc: | TODO @@ -3077,6 +3084,7 @@ callbacks: doc: | TODO type: out_string + ownership_doc: without - name: pop_error_scope doc: | TODO @@ -3094,6 +3102,7 @@ callbacks: doc: | TODO type: out_string + ownership_doc: without - name: queue_work_done doc: | TODO @@ -3116,10 +3125,12 @@ callbacks: doc: | TODO type: object.adapter + ownership_doc: with - name: message doc: | TODO type: out_string + ownership_doc: without - name: request_device doc: | TODO @@ -3133,10 +3144,12 @@ callbacks: doc: | TODO type: object.device + ownership_doc: with - name: message doc: | TODO type: out_string + ownership_doc: without - name: uncaptured_error doc: | TODO @@ -3147,6 +3160,7 @@ callbacks: TODO type: object.device pointer: immutable + ownership_doc: without - name: type doc: | TODO @@ -3155,6 +3169,7 @@ callbacks: doc: | TODO type: out_string + ownership_doc: without functions: - name: create_instance doc: Create a WGPUInstance @@ -3162,6 +3177,7 @@ functions: doc: | TODO type: object.instance + ownership_doc: with args: - name: descriptor doc: | @@ -3221,6 +3237,7 @@ objects: TODO type: struct.supported_features pointer: mutable + ownership_doc: with - name: get_info doc: | TODO @@ -3230,6 +3247,7 @@ objects: TODO type: struct.adapter_info pointer: mutable + ownership_doc: with - name: request_device doc: | TODO @@ -3378,6 +3396,7 @@ objects: doc: | TODO type: object.command_buffer + ownership_doc: with args: - name: descriptor doc: | @@ -3392,6 +3411,7 @@ objects: doc: | TODO type: object.compute_pass_encoder + ownership_doc: with args: - name: descriptor doc: | @@ -3406,6 +3426,7 @@ objects: doc: | TODO type: object.render_pass_encoder + ownership_doc: with args: - name: descriptor doc: | @@ -3671,6 +3692,7 @@ objects: doc: | TODO type: object.bind_group_layout + ownership_doc: with args: - name: group_index doc: | @@ -3695,6 +3717,7 @@ objects: doc: | TODO type: object.bind_group + ownership_doc: with args: - name: descriptor doc: | @@ -3708,6 +3731,7 @@ objects: doc: | TODO type: object.bind_group_layout + ownership_doc: with args: - name: descriptor doc: | @@ -3721,6 +3745,7 @@ objects: doc: | TODO type: object.buffer + ownership_doc: with args: - name: descriptor doc: | @@ -3734,6 +3759,7 @@ objects: doc: | TODO type: object.command_encoder + ownership_doc: with args: - name: descriptor doc: | @@ -3748,6 +3774,7 @@ objects: doc: | TODO type: object.compute_pipeline + ownership_doc: with args: - name: descriptor doc: | @@ -3771,6 +3798,7 @@ objects: doc: | TODO type: object.pipeline_layout + ownership_doc: with args: - name: descriptor doc: | @@ -3784,6 +3812,7 @@ objects: doc: | TODO type: object.query_set + ownership_doc: with args: - name: descriptor doc: | @@ -3807,6 +3836,7 @@ objects: doc: | TODO type: object.render_bundle_encoder + ownership_doc: with args: - name: descriptor doc: | @@ -3820,6 +3850,7 @@ objects: doc: | TODO type: object.render_pipeline + ownership_doc: with args: - name: descriptor doc: | @@ -3833,6 +3864,7 @@ objects: doc: | TODO type: object.sampler + ownership_doc: with args: - name: descriptor doc: | @@ -3847,6 +3879,7 @@ objects: doc: | TODO type: object.shader_module + ownership_doc: with args: - name: descriptor doc: | @@ -3860,6 +3893,7 @@ objects: doc: | TODO type: object.texture + ownership_doc: with args: - name: descriptor doc: | @@ -3909,6 +3943,7 @@ objects: TODO type: struct.supported_features pointer: mutable + ownership_doc: with - name: get_queue doc: | TODO @@ -3916,6 +3951,7 @@ objects: doc: | TODO type: object.queue + ownership_doc: with - name: push_error_scope doc: | TODO @@ -3945,6 +3981,7 @@ objects: returns: doc: A new @ref WGPUSurface for this descriptor (or an error @ref WGPUSurface). type: object.surface + ownership_doc: with args: - name: descriptor doc: The description of the @ref WGPUSurface to create. @@ -4294,6 +4331,7 @@ objects: doc: | TODO type: object.render_bundle + ownership_doc: with args: - name: descriptor doc: | @@ -4574,6 +4612,7 @@ objects: doc: | TODO type: object.bind_group_layout + ownership_doc: with args: - name: group_index doc: | @@ -4644,6 +4683,7 @@ objects: It may contain memory allocations so `::wgpuSurfaceCapabilitiesFreeMembers` must be called to avoid memory leaks. type: struct.surface_capabilities pointer: mutable + ownership_doc: with - name: get_current_texture doc: | Returns the @ref WGPUTexture to render to `surface` this frame along with metadata on the frame. @@ -4678,6 +4718,7 @@ objects: doc: | TODO type: object.texture_view + ownership_doc: with args: - name: descriptor doc: | From c6045282778fd2a8fcdffc5f763507a6787ec85a Mon Sep 17 00:00:00 2001 From: Kai Ninomiya Date: Wed, 16 Oct 2024 19:50:50 -0400 Subject: [PATCH 2/6] forgot to add --- doc/articles/Ownership.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 doc/articles/Ownership.md diff --git a/doc/articles/Ownership.md b/doc/articles/Ownership.md new file mode 100644 index 00000000..705dab32 --- /dev/null +++ b/doc/articles/Ownership.md @@ -0,0 +1,33 @@ +# Ownership {#Ownership} + +Objects in `webgpu.h` are refcounted via the `AddRef` and `Release` functions. +The refcount only changes when these methods are called explicitly (not, for example, in \ref wgpuCommandEncoderFinish or \ref wgpuQueueSubmit). + +Memory for variable-sized outputs from the API (message strings, capability arrays, etc.) is managed in different ways depending on whether they are returned values or callback arguments. + +## Returned with Ownership {#ReturnedWithOwnership} + +Objects returned directly from the API (e.g. \ref WGPUBuffer from \ref wgpuDeviceCreateBuffer and \ref WGPUTexture via \ref WGPUSurfaceTexture from \ref wgpuSurfaceGetCurrentTexture) start with one application-owned ref. +The application must `Release` this ref before losing the pointer. +(The returned object may _also_ have other refs, either API-owned refs or existing application-owned refs, but this should not be relied upon.) + +Variable-sized outputs returned from the API (e.g. the strings in \ref WGPUAdapterInfo, from \ref wgpuAdapterGetInfo) are application-owned. +The application must call the appropriate `FreeMembers` function (e.g. \ref wgpuAdapterInfoFreeMembers) before losing the pointers. +Note that such functions will *not* free any previously-allocated data: overwriting an output structure (e.g. using \ref wgpuAdapterGetInfo) without first calling `FreeMembers` (e.g. `wgpuAdapterInfoFreeMembers) will leak the allocations. + +## Callback Arguments {#CallbackArgs} + +Output arguments passed from the API to application callbacks include objects and message strings, which are passed to most callbacks. + +### Passed with Ownership {#PassedWithOwnership} + +Usually, object arguments passed to callbacks start with one application-owned ref, which the application must free before losing the pointer. + +### Passed without Ownership {#PassedWithoutOwnership} + +A.k.a. "pass by reference". + +Sometimes, object arguments passed to callbacks are non-owning - the application doesn't need to free them. + +Variable-sized outputs passed from the API to callbacks (such as message strings in most callbacks) are always owned by the API and guaranteed to be valid only during the callback's execution, after which the pointers passed to the callback are no longer valid. + From b81c6f63871e1a9aa974eff61e8d120336016688 Mon Sep 17 00:00:00 2001 From: Kai Ninomiya Date: Wed, 16 Oct 2024 19:52:45 -0400 Subject: [PATCH 3/6] fix --- gen/gen.go | 2 +- webgpu.h | 4 ---- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/gen/gen.go b/gen/gen.go index f311b256..5d685a99 100644 --- a/gen/gen.go +++ b/gen/gen.go @@ -68,7 +68,7 @@ func (g *Generator) Gen(dst io.Writer) error { if fn.Returns != nil { returnsDoc := strings.TrimSpace(fn.Returns.Doc) if returnsDoc != "" && returnsDoc != "TODO" { - s += "\n\n@returns\n\n" + returnsDoc + s += "\n\n@returns\n" + returnsDoc } } return Comment(strings.TrimSpace(s), CommentTypeMultiLine, indent, true) diff --git a/webgpu.h b/webgpu.h index fea80b3e..17ca6a35 100644 --- a/webgpu.h +++ b/webgpu.h @@ -3167,7 +3167,6 @@ WGPU_EXPORT WGPUProc wgpuGetProcAddress(WGPUStringView procName) WGPU_FUNCTION_A * This parameter is @ref ReturnedWithOwnership. * * @returns - * * Return @ref WGPUStatus_Error (and leaves `features` uninitialized) if: * * - `features` has an invalid struct chain. @@ -3350,7 +3349,6 @@ WGPU_EXPORT void wgpuDeviceDestroy(WGPUDevice device) WGPU_FUNCTION_ATTRIBUTE; * This parameter is @ref ReturnedWithOwnership. * * @returns - * * Return @ref WGPUStatus_Error (and leaves `features` uninitialized) if: * * - `features` has an invalid struct chain. @@ -3381,7 +3379,6 @@ WGPU_EXPORT void wgpuDeviceRelease(WGPUDevice device) WGPU_FUNCTION_ATTRIBUTE; * The description of the @ref WGPUSurface to create. * * @returns - * * A new @ref WGPUSurface for this descriptor (or an error @ref WGPUSurface). */ WGPU_EXPORT WGPUSurface wgpuInstanceCreateSurface(WGPUInstance instance, WGPUSurfaceDescriptor const * descriptor) WGPU_FUNCTION_ATTRIBUTE; @@ -3603,7 +3600,6 @@ WGPU_EXPORT void wgpuSurfaceConfigure(WGPUSurface surface, WGPUSurfaceConfigurat * This parameter is @ref ReturnedWithOwnership. * * @returns - * * TODO make this WGPUStatus instead of a boolean. */ WGPU_EXPORT WGPUBool wgpuSurfaceGetCapabilities(WGPUSurface surface, WGPUAdapter adapter, WGPUSurfaceCapabilities * capabilities) WGPU_FUNCTION_ATTRIBUTE; From 740ddf9a51b9b6b9f638bf46b863e93d28034da5 Mon Sep 17 00:00:00 2001 From: Kai Ninomiya Date: Wed, 16 Oct 2024 19:54:35 -0400 Subject: [PATCH 4/6] example --- doc/articles/Ownership.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/articles/Ownership.md b/doc/articles/Ownership.md index 705dab32..3feeece8 100644 --- a/doc/articles/Ownership.md +++ b/doc/articles/Ownership.md @@ -27,7 +27,7 @@ Usually, object arguments passed to callbacks start with one application-owned r A.k.a. "pass by reference". -Sometimes, object arguments passed to callbacks are non-owning - the application doesn't need to free them. +Sometimes, object arguments passed to callbacks are non-owning (such as the \ref WGPUDevice in \ref WGPUDeviceLostCallback) - the application doesn't need to free them. Variable-sized outputs passed from the API to callbacks (such as message strings in most callbacks) are always owned by the API and guaranteed to be valid only during the callback's execution, after which the pointers passed to the callback are no longer valid. From 01c13353e1c92534d82dfda47b7859541bccd52c Mon Sep 17 00:00:00 2001 From: Kai Ninomiya Date: Wed, 16 Oct 2024 20:02:09 -0400 Subject: [PATCH 5/6] fix case --- gen/gen.go | 4 ++-- webgpu.h | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/gen/gen.go b/gen/gen.go index 5d685a99..43c1bec0 100644 --- a/gen/gen.go +++ b/gen/gen.go @@ -62,7 +62,7 @@ func (g *Generator) Gen(dst io.Writer) error { sArg = strings.TrimSpace(sArg) if sArg != "" { - s += "\n\n@param " + arg.Name + "\n" + sArg + s += "\n\n@param " + CamelCase(arg.Name) + "\n" + sArg } } if fn.Returns != nil { @@ -97,7 +97,7 @@ func (g *Generator) Gen(dst io.Writer) error { sArg = strings.TrimSpace(sArg) if sArg != "" { - s += "\n\n@param " + arg.Name + "\n" + sArg + s += "\n\n@param " + CamelCase(arg.Name) + "\n" + sArg } } return Comment(strings.TrimSpace(s), CommentTypeMultiLine, indent, true) diff --git a/webgpu.h b/webgpu.h index 17ca6a35..de4617d2 100644 --- a/webgpu.h +++ b/webgpu.h @@ -1159,7 +1159,7 @@ typedef void (*WGPUProc)(void) WGPU_FUNCTION_ATTRIBUTE; */ typedef void (*WGPUBufferMapCallback)(WGPUMapAsyncStatus status, WGPUStringView message, WGPU_NULLABLE void* userdata1, WGPU_NULLABLE void* userdata2) WGPU_FUNCTION_ATTRIBUTE; /** - * @param compilation_info + * @param compilationInfo * This parameter is @ref PassedWithoutOwnership. */ typedef void (*WGPUCompilationInfoCallback)(WGPUCompilationInfoRequestStatus status, struct WGPUCompilationInfo const * compilationInfo, WGPU_NULLABLE void* userdata1, WGPU_NULLABLE void* userdata2) WGPU_FUNCTION_ATTRIBUTE; @@ -3607,7 +3607,7 @@ WGPU_EXPORT WGPUBool wgpuSurfaceGetCapabilities(WGPUSurface surface, WGPUAdapter * Returns the @ref WGPUTexture to render to `surface` this frame along with metadata on the frame. * See @ref Surface-Presenting for more details. * - * @param surface_texture + * @param surfaceTexture * The structure to fill the @ref WGPUTexture and metadata in. */ WGPU_EXPORT void wgpuSurfaceGetCurrentTexture(WGPUSurface surface, WGPUSurfaceTexture * surfaceTexture) WGPU_FUNCTION_ATTRIBUTE; From a0ed9fd4d44fdfb6d611cd9c46a8d2948256968f Mon Sep 17 00:00:00 2001 From: Kai Ninomiya Date: Wed, 16 Oct 2024 20:04:57 -0400 Subject: [PATCH 6/6] expand note to cover GetCurrentTexture --- doc/articles/Ownership.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/articles/Ownership.md b/doc/articles/Ownership.md index 3feeece8..f23701f3 100644 --- a/doc/articles/Ownership.md +++ b/doc/articles/Ownership.md @@ -13,7 +13,11 @@ The application must `Release` this ref before losing the pointer. Variable-sized outputs returned from the API (e.g. the strings in \ref WGPUAdapterInfo, from \ref wgpuAdapterGetInfo) are application-owned. The application must call the appropriate `FreeMembers` function (e.g. \ref wgpuAdapterInfoFreeMembers) before losing the pointers. -Note that such functions will *not* free any previously-allocated data: overwriting an output structure (e.g. using \ref wgpuAdapterGetInfo) without first calling `FreeMembers` (e.g. `wgpuAdapterInfoFreeMembers) will leak the allocations. + +Note that such functions will *not* free any previously-allocated data: overwriting an output structure without first freeing members will leak the allocations; e.g.: + +- Overwriting the strings in \ref WGPUAdapterInfo with \ref wgpuAdapterGetInfo without first calling \ref wgpuAdapterInfoFreeMembers. +- Overwriting the `texture` in \ref WGPUSurfaceTexture with \ref wgpuSurfaceGetCurrentTexture without first calling \ref wgpuTextureRelease. ## Callback Arguments {#CallbackArgs}