basic.tex

\Ch{Basic Concepts}{Basic}

\begin{note}
  \p HLSL inherits a significant portion of its language semantics from C and C++.
  Some of this is a result of intentional adoption of syntax early in the development
  of the language and some a side-effect of the Clang-based implementation of DXC.

  \p This chapter includes a lot of definitions that are inherited from C and C++.
  Some are identical to C or C++, others are slightly different. HLSL is neither
  a subset nor a superset of C or C++, and cannot be simply described in terms
  of C or C++. This specification includes all necessary definitions for clarity.
\end{note}

\Sec{Preamble}{Basic.preamble}

\p An \textit{entity} is a value, object, function, enumerator, type, class
member, bit-field, template, template specialization, namespace, or pack.

\p A \textit{name} is a use of an \textit{identifier} (\ref{Expr.Primary.ID}),
\textit{operator-function-id} (\ref{Overload.operator}),
\textit{conversion-function-id} (\ref{Classes.Conversions}),
or \textit{template-id} (\ref{Template}) that denotes any entity or
\textit{label} (\ref{Stmt.Label}).

\p Every name that denotes an entity is introduced by a \textit{declaration}.
Every name that denotes a label is introduced by a \textit{labeled statement}
(\ref{Stmt.Label})\footnote{HLSL does not have \texttt{goto}, and labeled
statements are only valid within \texttt{switch} statements.}.

\p A \textit{variable} is introduced by the declaration of a reference other
than a non-static data member of an object. The variable's name denotes the
reference or object.

\p Whenever a name is encountered it is necessary to determine if the name
denotes an entity that is a type or template. The process for determining if a
name refers to a type or template is called \textit{name lookup}.

\p Two names are the same name if:
\begin{itemize}
\item they are identifiers comprised of the same character sequence, or
\item they are operator-function-ids formed with the same operator, or
\item they are conversion-function-ids formed with the same type, or
\item they are template-ids that refer to the same class or function.
\end{itemize}

\p \begin{note}
  This section matches \gls{isoCPP} section \textbf{[basic]} except for the
  exclusion of \texttt{goto} and \textit{literal operators}.
\end{note}

\Sec{Declarations and definitions}{Basic.Decl}

\p A declaration (\ref{Decl}) may introduce one or more names into a translation
unit or redeclare names introduced by previous declarations. If a declaration
introduces names, it specifies the interpretation and attributes of these names.
A declaration may also have effects such as:
\begin{itemize}
\item verifying a static assertion (\ref{Decl}),
\item use of attributes (\ref{Decl}), and
\item controlling template instantiation (\ref{Template.Inst}).
\end{itemize}

\p A declaration is a \textit{definition} unless:
\begin{itemize}
\item it declares a function without specifying the function's body
(\ref{Decl.Function}),
\item it is a parameter declaration in a function declaration that does not
specify the function's body (\ref{Decl.Function}),
\item it is a global or namespace member declaration without the \texttt{static}
specifier\footnote{Global variable declarations are implicitly constant and
external in HLSL.},
\item it declares a static data member in a class definition,
\item it is a class name declaration,
\item it is a template parameter,
\item it is a \texttt{typedef} declaration (\ref{Decl}),
\item it is an \textit{alias-declaration} (\ref{Decl}),
\item it is a \textit{using-declaration} (\ref{Decl}),
\item it is a \textit{static\_assert-declaration} (\ref{Decl}),
\item it is an \textit{empty-declaration} (\ref{Decl}),
\item or a \textit{using-directive} (\ref{Decl}).
\end{itemize}

\p The two examples below are adapted from \gls{isoCPP} \textbf{[basic.def]}. All
but one of the following are definitions:
\begin{HLSL}
int f(int x) { return x+1; } // defines f and x
struct S {int a;int b;};     // defines S, S::a, and S::b
struct X {                   // defines X
  int x;                     // defines non-static member x
  static int y;              // declares static data member y
};
int X::y = 1;                // defines X::y
enum { up, down };           // defines up and down
namespace N {                // defines N
int d;                       // declares N::d
static int i;                // defines N::i
}
\end{HLSL}

\p All of the following are declarations:
\begin{HLSL}
int a;                       // declares a
const int c;                 // declares c
X anX;                       // declares anX
int f(int);                  // declares f
struct S;                    // declares S
typedef int Int;             // declares Int
using N::d;                  // declares d
using Float = float;         // declares Float
cbuffer CB {                 // does not declare CB
  int z;                     // declares z
}
tbuffer TB {                 // does not declare TB
  int w;                     // declares w
}
\end{HLSL}

\Sec{One-Definition Rule}{Basic.ODR}

\p The \gls{isoCPP} \textit{One-definition rule} is adopted as defined in
\gls{isoCPP} \textbf{[basic.def.odr]}.

\Sec{Scope}{Basic.Scope}

\Sec{Name Lookup}{Basic.Lookup}

\Sec{Program and linkage}{Basic.Linkage}

\p A translation unit (\ref{Lex.Translation}) is comprised of a sequence of
declarations:

\begin{grammar}
  \define{translation-unit}\br
  \opt{declaration-sequence}
\end{grammar}

\p A \textit{program} is one or more translation units \textit{linked} together.
A program built from a single translation unit, bypassing a linking step is
called \textit{freestanding}.

\p A program is said to be \textit{fully linked}, when it contains no
\textit{unresolved external} declarations, and all \textit{exported}
declarations are entry point declarations (\ref{Basic.Start}). A program is said
to be \textit{partially linked}, when it contains at least one unresolved
external declaration or at least one exported declaration that is not an entry
point.

\p An implementation may generate programs as fully linked or partially linked
as requested by the user, and a runtime may allow fully linked or partially
linked programs as the implementation allows.

\p A name has \textit{linkage} if it can refer to the same entity as a name
introduced by a declaration in another scope. If a variable, function, or
another entity with the same name is declared in several scopes, but does not
have sufficient \textit{linkage}, then several instances of the entity are
generated.

\begin{itemize}
\item A name with \textit{no linkage} may not be referred to by names from
any other scope.
\item A name with \textit{internal linkage} may be referred to by names
from other scopes within the same translation unit.
\item A name with \textit{external linkage} may be referred to by names from
other scopes within the same translation unit, and by names from scopes of other
translation units.
\item A name with \textit{program linkage} may be referred to by names from
other scopes within the same translation unit, by names from scopes of other
translation units, by names from scopes of other programs, and by a runtime
implementation.
\end{itemize}

\p When merging translation units through linking or generating a freestanding
program only names with program linkage must be retained in the final program.

\Sub{Program Linkage}{Basic.Linkage.Program}

\p Entities with \textit{program linkage} can be referred to from other
partially linked programs or a runtime implementation.

\p The following entities have program linkage:
\begin{itemize}
  \item entry point functions (\ref{Basic.Start})
  \item functions marked with \texttt{export} keyword (\ref{Decl.Export})
  \item declarations contained within an \textit{export-declaration-group} (\ref{Decl.Export})
\end{itemize}

\Sub{External Linkage}{Basic.Linkage.External}

\p Entities with \textit{external linkage} can be referred to from the scopes in
the other translation units and enable linking between them.

\p The following entities in HLSL have \textit{external linkage}:
\begin{itemize}
  \item global variables that are not marked \texttt{static} or
  \texttt{groupshared} \footnote{These are not really linked with other
  translation units but rather their values are loaded indirectly based on
  cbuffer mapping.}
  \item static data members of classes or template classes
\end{itemize}

\p Linkage of functions (including template functions) that are not entry points
or marked with \texttt{export} keyword is implementation dependent. \footnote{In
DXC today functions that are not entry points or exported have \textit{internal
linkage} by default. This can be overriden by \texttt{-default-linkage} compiler
option.}

\Sub{Internal Linkage}{Basic.Linkage.Internal}

\p Entities with \textit{internal linkage} can be referred to from all scopes in
the current translation unit.

\p The following entities in HLSL have \textit{internal linkage}:
\begin{itemize}
  \item global variables marked as \texttt{static} or \texttt{groupshared}
  \item all entities declared in an unnamed namespace or a namespace within an
  unnamed namespace
  \item enumerations
  \item classes or template classes, their member functions, and nested classes
  and enumerations
\end{itemize}

\Sub{No Linkage}{Basic.Linkage.NoLinkage}

\p An entity with \textit{no linkage} can be referred to only from the scope it
is in.

\p Any of the following entites declared at function scope or block scopes
derived from function scope have no linkage:
\begin{itemize}
  \item local variables
  \item local classes and their member functions
  \item other entities declared at function scope or block scopes derived from
  function scope that such as typedefs, enumerations, and enumerators
\end{itemize}

\Sec{Start}{Basic.Start}

\p A fully linked program shall contain one or more global functions, which are
the designated starting points for the program. These global functions are
called \textit{entry points}, because they denote the location where execution
inside the program begins.

\p Entry point functions have different requirements based on the target runtime
and execution mode (\ref{Basic.Start.Mode}).

\p Parameters to entry functions and entry function return types must be of
scalar, vector, or non-intangible class type (\ref{Basic.types}). Scalar and
vector parameters and return types must be annotated with semantic annotations
(\ref{Decl.Attr.Semantic}). Class type input and output parameters must have all
fields annotated with semantic annotations.

\Sub{Execution Mode}{Basic.Start.Mode}

\p A runtime may define a set of execution modes in an implementation defined
way. Each execution mode will have a set of implementation defined rules which
restrict available language functionality as appropriate for the execution mode.

\Sec{Types}{Basic.types}

\p The \textit{object representation} of an object of type \texttt{T} is the
sequence of \textit{N} bytes taken up by the object of type \texttt{T}, where
\textit{N} equals \texttt{sizeof(T)}\footnote{\texttt{sizeof(T)} returns the
size of the object as-if it's stored in device memory, and determining the size
if it's stored in another memory space is not possible.}. The \textit{object
representation} of an object may be different based on the \textit{memory space}
it is stored in (\ref{Intro.Memory.Spaces}).

\p The \textit{value representation} of an object is the set of bits that hold
the value of type \texttt{T}. Bits in the object representation that are not
part of the value representation are \textit{padding bits}.

\p An \textit{object type} is a type that is not a function type, not a
reference type, and not a void type.

\p A \textit{class type} is a data type declared with either the \texttt{class}
or \texttt{struct} keywords (\ref{Classes}). A class type \texttt{T} may be
declared as incomplete at one point in a translation unit via a \textit{forward
declaration}, and complete later with a full definition. The type \texttt{T} is
the same type throughout the translation unit.

\p There are special implementation-defined types such as \textit{handle types},
which fall into a category of \textit{standard intangible types}. Intangible
types are types that have no defined object representation or value
representation, as such the size is unknown at compile time.
% Note: The above definition is likely incomplete, and it is unclear if minimum
% precision types should be intangible.

\p A class type \texttt{T} is an \textit{intangible class type} if it contains
a base class or members of intangible class type, standard intangible type,
or arrays of such types. Standard intangible types and intangible class types
are collectively called \textit{intangible types}(\ref{Intangible}).

\p An object type is an \textit{incomplete type} if the compiler lacks
sufficient information to determine the size of an object of type \texttt{T},
and it is not an intangible type. It is a \textit{complete type} if the compiler
has sufficient information to determine the size of an object of type
\texttt{T}, or if the type is known to be an intangible type. An object may not
be defined to have an \textit{incomplete} type.

\p Arithmetic types (\ref{Basic.types.arithmetic}), enumeration types, and
\textit{cv-qualified} versions of these types are collectively called
\textit{scalar types}.

\p Vectors of scalar types declared with the built-in \texttt{vector<T,N>}
template are \textit{vector types}. Vector lengths must be between 1 and 4 (i.e.
\( 1 \leq N \leq 4 \) ).

\p Matrices of scalar types declared with the built-in \texttt{matrix<T,N,M>}
template are \textit{matrix types}. Matrix dimensions, \texttt{N} and
\texttt{M}, must be between 1 and 4 (i.e. \( 1 \leq N \leq 4 \) ).

\Sub{Arithmetic Types}{Basic.types.arithmetic}

\p There are three \textit{standard signed integer types}: \texttt{int16\_t},
\texttt{int32\_t}, and \texttt{int64\_t}. Each of the signed integer types is
explicitly named for the size in bits of the type's object representation. There
is also the type alias \texttt{int} which is an alias of \texttt{int32\_t}.
There is one \textit{minimum precision signed integer type}: \texttt{min16int}.
The minimum precision signed integer type is named for the required minimum
value representation size in bits. The object representation of
\texttt{min16int} is \texttt{int}. The standard signed integer types and minimum
precision signed integer type are collectively called \textit{signed integer
types}.

\p There are three \textit{standard unsigned integer types}: \texttt{uint16\_t},
\texttt{uint32\_t}, and \texttt{uint64\_t}. Each of the unsigned integer types
is explicitly named for the size in bits of the type's object representation.
There is also the type alias \texttt{uint} which is an alias of
\texttt{uint32\_t}. There is one \textit{minimum precision unsigned integer
type}: \texttt{min16uint}. The minimum precision unsigned integer type is named
for the required minimum value representation size in bits. The object
representation of \texttt{min16uint} is \texttt{uint}. The standard unsigned
integer types and minimum precision unsigned integer type are collectively
called \textit{unsigned integer types}.

\p The minimum precision signed integer types and minimum precision unsigned
integer types are collectively called \textit{minimum precision integer types}.
The standard signed integer types and standard unsigned integer types are
collectively called \textit{standard integer types}. The signed integer types
and unsigned integer types are collectively called \textit{integer types}.
Integer types inherit the object representation of integers defined in
\glsdesc{isoC23}\footnote{C23 adopts two's compliment as the object
representation for integer types.}. Integer types shall satisfy the constraints
defined in \glsdesc{isoCPP}, section \textbf{basic.fundamental}.

\p There are three \textit{standard floating point types}: \texttt{half},
\texttt{float}, and \texttt{double}. The \texttt{float} type is a 32-bit
floating point type. The \texttt{double} type is a 64-bit floating point type.
Both the \texttt{float} and \texttt{double} types have object representations as
defined in \gls{IEEE754}. The \texttt{half} type may be either 16-bit or 32-bit
as controlled by implementation defined compiler settings. If \texttt{half} is
32-bit it will have an object representation as defined in \gls{IEEE754},
otherwise it will have an object representation matching the \textbf{binary16}
format defined in \gls{IEEE754}\footnote{IEEE-754 only defines a binary encoding
for 16-bit floating point values, it does not fully specify the behavior of such
types.}. There is one \textit{minimum precision floating point type}:
\texttt{min16float}. The minimum precision floating point type is named for the
required minimum value representation size in bits. The object representation of
\texttt{min16float} is \texttt{float}\footnote{This means when stored to memory
objects of type \texttt{min16float} are stored as \textbf{binary32} as defined
in \gls{IEEE754}.}. The standard floating point types and minimum precision
floating point type are collectively called \textit{floating point types}.

\p Integer and floating point types are collectively called \textit{arithmetic
types}.

\p The \texttt{void} type is inherited from \gls{isoCPP}, which defines it as
having an empty set of values and being an incomplete type that can never be
completed. The \texttt{void} type is used to signify the return type of a
function that returns no value. Any expression can be explicitly converted to
\texttt{void}.

\Sub{Scalarized Type Compatability}{Basic.types.scalarized}

\p All types \texttt{T} have a \textit{scalarized representation}, \(SR(T)\),
which is a list of one or more types representing each scalar element of
\texttt{T}.

\p Scalarized representations are determined as follows:
\begin{itemize}
\item The scalarized representation of an array \texttt{T[n]} is \(SR(T_0), ..
SR(T_n)\).

\item The scalarized representation of a vector \texttt{vector<T,n>} is \(T_0,
.. T_n\).

\item The scalarized representation of a matrix \texttt{matrix<T,n, m>} is
\(T_0, .. T_{n \times m}\).

\item The scalarized representation of a class type \texttt{T}, \(SR(T)\) is
computed recursively as \(SR(T::base), SR(T::_0), .. SR(T::_n)\) where
\texttt(T::base) is \texttt{T}'s base class if it has one, and \(T::_n\)
represents the \textit{n} non-static members of \texttt{T}.

\item The scalarized representation for an enumeration type is the underlying
arithmetic type.

\item The scalarized representation for arithmetic, intangible types, and any other
type \texttt{T} is \(T\).
\end{itemize}

\p Two types \textit{cv1} \texttt{T1} and \textit{cv2} \texttt{T2} are
\textit{scalar-layout-compatible types} if \texttt{T1} and \texttt{T2} are the same
type or if the sequence of types defined by the scalar representation \(SR(T1)\)
and scalar representation \(SR(T2)\) are identical.

\Sec{Storage Duration}{Basic.Storage}
\Sec{Lvalues and rvalues}{Basic.lval}

\p Expressions are classified by the type(s) of values they produce. The valid
types of values produced by expressions are:

\begin{enumerate}
  \item An \textit{lvalue} represents a function or object.
  \item An \textit{rvalue} represents a temporary object.
  \item An \textit{xvalue} (expiring value) represents an object near the end
  of its lifetime.
  \item A \textit{cxvalue} (casted expiring value) is an \textit{xvalue}
  which, on expiration, assigns its value to a bound \textit{lvalue}.
  \item A \textit{glvalue} is an \textit{lvalue}, \textit{xvalue}, or
  \textit{cxvalue}.
  \item A \textit{prvalue} is an \textit{rvalue} that is not an \textit{xvalue}.
\end{enumerate}