Skip to content

Commit

Permalink
Add a <<fundamentals-strings, String Representation>> section clarify…
Browse files Browse the repository at this point in the history
…ing (#2365)

that UTF-8 strings returned from queries in fixed-length buffers will
always include the null terminator in that buffer (public issue 2351).
  • Loading branch information
oddhack committed May 10, 2024
1 parent 632ab09 commit 6a32915
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 3 deletions.
4 changes: 2 additions & 2 deletions appendices/vulkanscdeviations.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
|===
Expand Down
42 changes: 41 additions & 1 deletion chapters/fundamentals.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<fundamentals-strings, String Representation>> for additional
information about strings.


[[fundamentals-validusage-enums]]
==== Valid Usage for Enumerated Types
Expand Down Expand Up @@ -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

Expand Down

0 comments on commit 6a32915

Please sign in to comment.