search

microsoft / hlsl-specs

HLSL Specifications
MIT License
118 stars 30 forks source link

[Language] Begin Basic.types #198

Closed llvm-beanz closed 4 months ago

llvm-beanz commented 5 months ago

This begins drafting the Basic.types section which specifies the foundations of HLSL's data types. This includes some basic information about representations as well as the classifications of types and the basic behaviors of some types.

Fixes #195

llvm-beanz commented 5 months ago

The PDF build is here: https://github.com/microsoft/hlsl-specs/actions/runs/8724175011/artifacts/1422465192

In case anyone doesn't like reading LaTeX.

llvm-beanz commented 5 months ago

Note: While I see classes.tex in the sources here, it doesn't seem to be rendered in the artifact here: https://github.com/microsoft/hlsl-specs/actions/runs/8726130788/artifacts/1422979344. Similarly, the "Intangible Types" page there is blank - is that missing or do you intend to put it there as a placeholder to be filled in later?

I meant to delete classes.tex and somehow re-added it. Clearly git and I don't get along. It is removed now.

The classes and intangible types chapters are placeholders to be filled out later. I thought it was better to have references to empty sections rather than a bunch of TODO comments to add references later.

bharadwajy commented 5 months ago

Several (may be all?) of the definitions of the HLSL language concepts specified here appear (by design and choice, I presume) very similar to those of C++, for example types. If so, would it be prudent to defer to the public C++ specification for concepts that are the same in HLSL and C++ while providing details of concepts and support that is specific to HLSL and differ from C++? This could prevent ambiguous interpretation of concepts supported in both the languages owing to potentially different verbiage.

llvm-beanz commented 4 months ago

Several (may be all?) of the definitions of the HLSL language concepts specified here appear (by design and choice, I presume) very similar to those of C++, for example types. If so, would it be prudent to defer to the public C++ specification for concepts that are the same in HLSL and C++ while providing details of concepts and support that is specific to HLSL and differ from C++? This could prevent ambiguous interpretation of concepts supported in both the languages owing to potentially different verbiage.

In general, I think this is really great and important feedback. I've tried to cite the C and C++ specifications where possible. You'll note glossary references to isoC23, and isoCPP in this PR. I've also cited IEEE754 where I could instead of defining the floating point type representations. Unfortunately a lot of our behaviors are subtly different from C and C++, so citing the existing specifications doesn't really make sense.

For example in this PR, HLSL defines size-specified integer types, and the floating point type have explicitly defined sizes too. While we do satisfy C's guarantee that float is <= the size of double, in HLSL we can make a stronger guarantee. We also have the min-precision types which have completely different challenges. Because of those differences neither C nor C++'s definitions of arithmetic types fit HLSL.

Probably about the only direct overlap in this PR between HLSL and C++ is the definitions of object representation, value representation and object type. I deliberately chose to define those terms (even if slightly differently) so that the definition is in our document. My main reasoning is that it would suck when reading the spec to need to jump to another document to find a single-sentence term definition, and those definitions can move around between versions of the specification.

There is some shared language around Classes, but HLSL classes are very different from C++ so I really don't want to cite C++ too much in that part of the document because I don't want to mislead people into thinking the languages align more than they do.

For the purpose of this PR I think we have very little that we can directly inherit from C or C++ beyond what I've already cited without a whole lot of extra qualifying language (i.e. "It's like C++ but with these differences..."). If you think I missed something where we could more concisely just cite the C or C++ specification please let me know.