Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a <<fundamentals-strings, String Representation>> section #2365

Merged
merged 1 commit into from
May 10, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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