From 2b8c4d5f0f276a1d8e9cf764af9a05f0e49beb64 Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Wed, 8 May 2024 02:43:30 -0700 Subject: [PATCH] Add a <> section clarifying that UTF-8 strings returned from queries in fixed-length buffers will always include the null terminator in that buffer (public issue 2351). --- appendices/vulkanscdeviations.adoc | 4 +-- chapters/fundamentals.adoc | 42 +++++++++++++++++++++++++++++- 2 files changed, 43 insertions(+), 3 deletions(-) diff --git a/appendices/vulkanscdeviations.adoc b/appendices/vulkanscdeviations.adoc index b20acf64a..a4efa00d1 100644 --- a/appendices/vulkanscdeviations.adoc +++ b/appendices/vulkanscdeviations.adoc @@ -181,8 +181,8 @@ a framework for handling deviations. |Directive |4.6: "_typedefs_ that indicate size and signedness should be used in place of the basic numerical types" |Category |Advisory -|Note |This is reported for every `char` and `float` variable used in the - API. +|Note |This is reported for every code:char and code:float variable + used in the API. |Rationale |Vulkan SC maintains the Base Vulkan type conventions for compatibility between APIs. |=== diff --git a/chapters/fundamentals.adoc b/chapters/fundamentals.adoc index 5f611b416..2a55e2b8a 100644 --- a/chapters/fundamentals.adoc +++ b/chapters/fundamentals.adoc @@ -965,10 +965,15 @@ a structure) satisfy the alignment requirements of the host processor. [[fundamentals-validusage-strings]] ==== Valid Usage for Strings -Any parameter that is a pointer to `char` must: be a finite sequence of +Any parameter that is a pointer to code:char must: be a finite sequence of values terminated by a null character, or if _explicitly called out in the Specification_, can: be `NULL`. +Strings specified as UTF-8 encoded must: not contain invalid UTF-8 +sequences. +See <> for additional +information about strings. + [[fundamentals-validusage-enums]] ==== Valid Usage for Enumerated Types @@ -1815,6 +1820,41 @@ This equation is used everywhere that floating-point values are converted to signed normalized fixed-point. +[[fundamentals-strings]] +== String Representation + +Strings passed into and returned from Vulkan API commands are usually +defined to be null-terminated and UTF-8 encoded. + +[NOTE] +.Note +==== +Exceptions to this rule exist only when strings are defined or used by +operating system APIs where that OS has a different convention. +For example, slink:VkExportMemoryWin32HandleInfoKHR::pname:name is a +null-terminated UTF-16 encoded string used in conjunction with Windows +handles. +==== + +When a UTF-8 string is *returned from* a Vulkan API query, it is returned in +a fixed-length buffer of C code:char. +For example, a string returned in +slink:VkPhysicalDeviceProperties::pname:deviceName has maximum length +ename:VK_MAX_PHYSICAL_DEVICE_NAME_SIZE, and a string returned in +slink:VkExtensionProperties::pname:extensionName has maximum length +ename:VK_MAX_EXTENSION_NAME_SIZE. +The string, *including* its null terminator, will always fit completely +within this buffer. +If the string is shorter than the buffer size, the contents of code:char +in the buffer following the null terminator are undefined:. + +When a UTF-8 string is *passed into* a Vulkan API, such as +slink:VkDeviceCreateInfo::pname:ppEnabledExtensionNames, there is no +explicit limit on the length of that string. +However, the string must: contain a valid UTF-8 encoded string and must: be +null-terminated. + + [[fundamentals-common-objects]] == Common Object Types