From 4c76b275907cf2d764f3fc51468d1c58635a10c1 Mon Sep 17 00:00:00 2001 From: Theresa Foley <10618364+tangent-vector@users.noreply.github.com> Date: Mon, 12 May 2025 10:28:05 -0700 Subject: Cleanups related to RIFF support (#7041) --- source/core/slang-common.h | 136 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 126 insertions(+), 10 deletions(-) (limited to 'source/core/slang-common.h') diff --git a/source/core/slang-common.h b/source/core/slang-common.h index 2aec6f0ce..9248e250f 100644 --- a/source/core/slang-common.h +++ b/source/core/slang-common.h @@ -4,6 +4,7 @@ #include "slang.h" #include +#include #include #define VARIADIC_TEMPLATE @@ -11,35 +12,150 @@ namespace Slang { +/// Signed 32-bit integer. +/// +/// This type should be used when the exact size +/// in bits is important (e.g., when dealing with +/// explicit binary file formats, etc.). Otherwise +/// prefer the plain `Int` type or a semantically +/// richer type like `Count` or `Index`. +/// typedef int32_t Int32; + +/// Unsigned 32-bit integer. +/// +/// This type should be used when the exact size +/// in bits is important (e.g., when dealing with +/// explicit binary file formats, etc.). Otherwise +/// prefer the plain `Int` type or a semantically +/// richer type like `Count` or `Index`. +/// typedef uint32_t UInt32; +/// Signed 64-bit integer. +/// +/// This type should be used when the exact size +/// in bits is important (e.g., when dealing with +/// explicit binary file formats, etc.). Otherwise +/// prefer the plain `Int` type or a semantically +/// richer type like `Count` or `Index`. +/// typedef int64_t Int64; + +/// Unsigned 64-bit integer. +/// +/// This type should be used when the exact size +/// in bits is important (e.g., when dealing with +/// explicit binary file formats, etc.). Otherwise +/// prefer the plain `Int` type or a semantically +/// richer type like `Count` or `Index`. +/// typedef uint64_t UInt64; -// Define -typedef SlangUInt UInt; +/// "Default" integer type for the Slang codebase. +/// +/// When there is not a clear reason to another +/// integer type, use this one. +/// +/// Note that this type is currently defined to be +/// the same as the `SlangInt` type exposed through +/// the public Slang API, but this may not be the +/// case forever. +/// typedef SlangInt Int; +/// "Default" unsigned integer type for the Slang codebase. +/// +/// Only use this type when you explicitly need +/// an unsigned type that's the same size as `Int`. +/// Otherwise you should probably just be using `Int`. +/// +/// Note that this type is currently defined to be +/// the same as the `SlangUInt` type exposed through +/// the public Slang API, but this may not be the +/// case forever. +/// +typedef SlangUInt UInt; + static const UInt kMaxUInt = ~UInt(0); static const Int kMaxInt = Int(kMaxUInt >> 1); -// typedef unsigned short Word; - typedef intptr_t PtrInt; -// TODO(JS): It looks like Index is actually 64 bit on 64 bit targets(!) -// Previous discussions landed on Index being int32_t. - -// Type used for indexing, in arrays/views etc. Signed. +/// Default type for indices. +/// +/// This is (and should always be) an alias for `Int`. +/// +/// Use this type to document the intention that an +/// integer parameter/variable/etc. represents an +/// index into some kind of sequence, or any other +/// kind of ordinal number. +/// typedef Int Index; + +static const Index kMaxIndex = kMaxInt; + +/// Unsigned equivalent of `Index`. +/// +/// Please don't use this unless you have a good reason. +/// typedef UInt UIndex; + +/// Default type for counts. +/// +/// This is (and should always be) an alias for `Int`. +/// +/// Use this type to document the intention that an +/// integer parameter/variable/etc. represents a +/// count of the number of elements in some container, +/// or any other kind of cardinal number. +/// typedef Int Count; + +/// Unsigned equivalent of `Count`. +/// +/// Please don't use this unless you have a good reason. +/// typedef UInt UCount; -static const Index kMaxIndex = kMaxInt; -typedef uint8_t Byte; +/// Explicit type for when manipulating bytes. +/// +/// Use this type to document the intention that a +/// parameter/variable/etc. represents an 8-bit byte, with +/// no particular interpretation of that byte as +/// any higher-level type. +/// +/// Note that the `char` types have special semantics +/// when it comes to "type punning" that are not shared +/// with other types like `uint8_t`. Using a variation +/// of `char` here helps avoid the possibility of undefined +/// behavior when code reads other types to/from arrays +/// of `Byte`s. +/// +/// We are not using `std::byte` here because that is +/// defined as an `enum class` and does not support +/// mathematical or bitwise operations, which a lot +/// of the Slang codebase does on `Byte`s. +/// +typedef unsigned char Byte; + +/// Preferred integer type for sizes measured in bytes. +/// +/// Use this type to document the intention that an +/// integer parameter/variable/etc. represents the +/// size of something, in bytes, rather than being +/// some other kind of integer. +/// +/// Note that this type is unsigned, despite the stated +/// default in the Slang codebase being signed integer +/// types. The reason for this is that variables +/// holding sizes are often compared against the +/// result of the `sizeof` operator, which yields +/// a `size_t`. Our hands are, to some extent, tied +/// on this matter. +/// +using Size = size_t; // TODO(JS): // Perhaps these should be named Utf8, Utf16 and UnicodePoint/Rune/etc? For now, just keep it simple -- cgit v1.2.3