Skip to content

Commit 11111e5

Browse files
csyonghecsyonghe
authored
Support visibility control and default to internal. (shader-slang#3380)
* Support visibility control and default to `internal`. * Fix wip. * Fixes. * Fix. * Fix test. * Add legacy language detection and compatibility for existing code. * Add doc. --------- Co-authored-by: Yong He <yhe@nvidia.com>
1 parent fa6d871 commit 11111e5

File tree

104 files changed

+2180
-1400
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

104 files changed

+2180
-1400
lines changed

‎docs/user-guide/04-modules-and-access-control.md

+169
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
2+
---
3+
layout: user-guide
4+
---
5+
6+
Modules and Access Control
7+
===========================
8+
9+
While the preprocessor `#include`s is still supported, Slang provides a _module_ system for software engineering benefits such as clean expression of sub-component boundaries and dependencies, hiding implementation details, and providing a path towards true separate compilation.
10+
11+
12+
### Defining a Module
13+
14+
A module in Slang comprises one or more files. A module must have one and only one primary file that is used as the source-of-truth to uniquely identify the module. The primary file must start with `module` declaration. For example, the following code defines a module named `scene`:
15+
16+
```
17+
// scene.slang
18+
19+
module scene;
20+
21+
// ...
22+
```
23+
24+
A module can contain more than one file. The additional files are pulled into the module with the `__include` syntax:
25+
26+
```
27+
// scene.slang
28+
29+
module scene;
30+
31+
__include "scene-helpers";
32+
33+
```
34+
```
35+
// scene-helpers.slang
36+
37+
implementing scene;
38+
// ...
39+
```
40+
41+
The files being included into a module must start with `implementing <module-name>` declaration.
42+
43+
Note that the `__include` syntax here has a different meaning than the preprocessor `#include`. `__include` has the following semantics:
44+
1. The preprocessor state at which a file inclusion does not apply to the file being included, and the preprocessor state after parsing the included file will not be visible to the outer "includer" file. For example, `#define`s before a `__include` is not visible to the included file, and `#define`s in the included file is not visible to the file that includes it.
45+
2. A file will be included into the current module exactly once, no matter how many times a `__include` of that file is encountered.
46+
3. Circular `__include`s are allowed, given (2).
47+
4. All files that become part of a module via `__include` can access all other entities defined in the same module, regardless the order of `__include`s.
48+
49+
This means that the following code is valid:
50+
51+
```
52+
// a.slang
53+
implementing m;
54+
void f_a() {}
55+
56+
// b.slang
57+
implementing "m"; // alternate syntax.
58+
__include a; // pulls in `a` to module `m`.
59+
void f_b() { f_a(); }
60+
61+
// c.slang
62+
implementing "m.slang"; // alternate syntax.
63+
// OK to use f_a and f_b because they are part of module `m`, even
64+
// if we are not including `a` and `b` here.
65+
void f_c() { f_a(); f_b(); }
66+
67+
// m.slang
68+
module m;
69+
__include m; // OK, a file including itself is allowed and has no effect.
70+
__include "b"; // Pulls in file b (alternate syntax), and transitively pulls in file a.
71+
__include "c.slang"; // Pulls in file c, specifying the full file name.
72+
void test() { f_a(); f_b(); f_c(); }
73+
```
74+
75+
Note that both `module`, `implementing` and `__include` support two flavors of syntax to refer to a module or a file: either via
76+
normal identifier tokens or via string literals. For example, the following flavors are equivalent and will resolve to the same file:
77+
```
78+
__include dir.file_name; // `file_name` is translated to "file-name".
79+
__include "dir/file-name.slang";
80+
__include "dir/file-name";
81+
```
82+
83+
> #### Note ####
84+
> When using the identifier token syntax, Slang will translate any underscores(`_`) to hyphenators("-") to obtain the file name.
85+
86+
### Importing a Module
87+
88+
At the global scope of a Slang file, you can use the `import` keyword to import another module by name:
89+
90+
```hlsl
91+
// MyShader.slang
92+
93+
import YourLibrary;
94+
```
95+
96+
This `import` declaration will cause the compiler to look for a module named `YourLibrary` and make its declarations visible in the current scope. Similar to `__include`, `import` also supports both the identifier-token and the file-name string syntax.
97+
98+
You can only `import` a primary source file of a module. For example, given:
99+
```
100+
// m.slang
101+
module m;
102+
__include helper;
103+
104+
// helper.slang
105+
implementing m;
106+
// ...
107+
```
108+
It is only valid for the user code to `import m`. Attempting to `import helper` will result a compile-time error.
109+
110+
Multiple `import`s of the same module from different input files will only cause the module to be loaded once (there is no need for "include guards" or `#pragma once`).
111+
Note that preprocessor definitions in the current file will not affect the compilation of `import`ed code, and the preprocessor definitions in the imported code is not visible to the current file.
112+
113+
> #### Note ####
114+
> Future versions of the Slang system will support loading of modules from pre-compiled binaries instead of source code.
115+
> The same `import` keyword will continue to work in that case.
116+
117+
### Access Control
118+
119+
Slang supports access control modifiers: `public`, `internal` and `private`. The module boundary plays an important role in access control.
120+
121+
`public` symbols are accessible everywhere: from within the different types, different files or different modules.
122+
123+
`private` symbols are only visible to other symbols in the same type. The following example shows the scope of `private` visibility:
124+
```csharp
125+
struct MyType
126+
{
127+
private int member;
128+
129+
int f() { member = 5; } // OK.
130+
131+
struct ChildType
132+
{
133+
int g(MyType t)
134+
{
135+
return t.member; // OK.
136+
}
137+
}
138+
}
139+
140+
void outerFunc(MyType t)
141+
{
142+
t.member = 2; // Error, `member` is not visible here.
143+
}
144+
```
145+
146+
`internal` symbols are visible throughout the same module, regardless if it is referenced from the same type or same file. But they are not visible to other modules. The following example shows the scope of `internal` visibility:
147+
148+
```csharp
149+
// a.slang
150+
module a;
151+
__include b;
152+
internal void f() { f_b(); } // OK, f_b defined in the same module.
153+
154+
// b.slang
155+
implementing a;
156+
internal void f_b(); // Defines f_b in module a so they can within the module.
157+
public void publicFunc();
158+
159+
// m.slang
160+
module m;
161+
import a;
162+
void main()
163+
{
164+
f(); // Error, f is not visible here.
165+
publicFunc(); // OK.
166+
}
167+
```
168+
169+
`internal` is the default visibility if no other access modifiers are specified.

‎docs/user-guide/04-interfaces-generics.md ‎docs/user-guide/05-interfaces-generics.md

File renamed without changes.

‎docs/user-guide/05-compiling.md ‎docs/user-guide/06-compiling.md

File renamed without changes.

‎docs/user-guide/06-targets.md ‎docs/user-guide/07-targets.md

File renamed without changes.

‎docs/user-guide/07-autodiff.md ‎docs/user-guide/08-autodiff.md

File renamed without changes.

‎docs/user-guide/toc.html

+37-35
Original file line numberDiff line numberDiff line change
@@ -45,51 +45,53 @@
4545
<li data-link="03-convenience-features#modules"><span>Modules</span></li>
4646
</ul>
4747
</li>
48-
<li data-link="04-interfaces-generics"><span>Interfaces and Generics</span>
48+
<li data-link="04-modules-and-access-control"><span>Modules and Access Control</span>
49+
</li>
50+
<li data-link="05-interfaces-generics"><span>Interfaces and Generics</span>
4951
<ul class="toc_list">
50-
<li data-link="04-interfaces-generics#interfaces"><span>Interfaces</span></li>
51-
<li data-link="04-interfaces-generics#generics"><span>Generics</span></li>
52-
<li data-link="04-interfaces-generics#supported-constructs-in-interface-definitions"><span>Supported Constructs in Interface Definitions</span></li>
53-
<li data-link="04-interfaces-generics#associated-types"><span>Associated Types</span></li>
54-
<li data-link="04-interfaces-generics#generic-value-parameters"><span>Generic Value Parameters</span></li>
55-
<li data-link="04-interfaces-generics#interface-typed-values"><span>Interface-typed Values</span></li>
56-
<li data-link="04-interfaces-generics#extending-a-type-with-additional-interface-conformances"><span>Extending a Type with Additional Interface Conformances</span></li>
57-
<li data-link="04-interfaces-generics#is-and-as-operator"><span>`is` and `as` Operator</span></li>
58-
<li data-link="04-interfaces-generics#extensions-to-interfaces"><span>Extensions to Interfaces</span></li>
52+
<li data-link="05-interfaces-generics#interfaces"><span>Interfaces</span></li>
53+
<li data-link="05-interfaces-generics#generics"><span>Generics</span></li>
54+
<li data-link="05-interfaces-generics#supported-constructs-in-interface-definitions"><span>Supported Constructs in Interface Definitions</span></li>
55+
<li data-link="05-interfaces-generics#associated-types"><span>Associated Types</span></li>
56+
<li data-link="05-interfaces-generics#generic-value-parameters"><span>Generic Value Parameters</span></li>
57+
<li data-link="05-interfaces-generics#interface-typed-values"><span>Interface-typed Values</span></li>
58+
<li data-link="05-interfaces-generics#extending-a-type-with-additional-interface-conformances"><span>Extending a Type with Additional Interface Conformances</span></li>
59+
<li data-link="05-interfaces-generics#is-and-as-operator"><span>`is` and `as` Operator</span></li>
60+
<li data-link="05-interfaces-generics#extensions-to-interfaces"><span>Extensions to Interfaces</span></li>
5961
</ul>
6062
</li>
61-
<li data-link="05-compiling"><span>Compiling Code with Slang</span>
63+
<li data-link="06-compiling"><span>Compiling Code with Slang</span>
6264
<ul class="toc_list">
63-
<li data-link="05-compiling#concepts"><span>Concepts</span></li>
64-
<li data-link="05-compiling#command-line-compilation-with-slangc"><span>Command-Line Compilation with `slangc`</span></li>
65-
<li data-link="05-compiling#using-the-compilation-api"><span>Using the Compilation API</span></li>
65+
<li data-link="06-compiling#concepts"><span>Concepts</span></li>
66+
<li data-link="06-compiling#command-line-compilation-with-slangc"><span>Command-Line Compilation with `slangc`</span></li>
67+
<li data-link="06-compiling#using-the-compilation-api"><span>Using the Compilation API</span></li>
6668
</ul>
6769
</li>
68-
<li data-link="06-targets"><span>Supported Compilation Targets</span>
70+
<li data-link="07-targets"><span>Supported Compilation Targets</span>
6971
<ul class="toc_list">
70-
<li data-link="06-targets#background-and-terminology"><span>Background and Terminology</span></li>
71-
<li data-link="06-targets#direct3d-11"><span>Direct3D 11</span></li>
72-
<li data-link="06-targets#direct3d-12"><span>Direct3D 12</span></li>
73-
<li data-link="06-targets#vulkan"><span>Vulkan</span></li>
74-
<li data-link="06-targets#opengl"><span>OpenGL</span></li>
75-
<li data-link="06-targets#cuda-and-optix"><span>CUDA and OptiX</span></li>
76-
<li data-link="06-targets#cpu-compute"><span>CPU Compute</span></li>
77-
<li data-link="06-targets#summary"><span>Summary</span></li>
72+
<li data-link="07-targets#background-and-terminology"><span>Background and Terminology</span></li>
73+
<li data-link="07-targets#direct3d-11"><span>Direct3D 11</span></li>
74+
<li data-link="07-targets#direct3d-12"><span>Direct3D 12</span></li>
75+
<li data-link="07-targets#vulkan"><span>Vulkan</span></li>
76+
<li data-link="07-targets#opengl"><span>OpenGL</span></li>
77+
<li data-link="07-targets#cuda-and-optix"><span>CUDA and OptiX</span></li>
78+
<li data-link="07-targets#cpu-compute"><span>CPU Compute</span></li>
79+
<li data-link="07-targets#summary"><span>Summary</span></li>
7880
</ul>
7981
</li>
80-
<li data-link="07-autodiff"><span>Automatic Differentiation</span>
82+
<li data-link="08-autodiff"><span>Automatic Differentiation</span>
8183
<ul class="toc_list">
82-
<li data-link="07-autodiff#using-automatic-differentiation-in-slang"><span>Using Automatic Differentiation in Slang</span></li>
83-
<li data-link="07-autodiff#mathematic-concepts-and-terminologies"><span>Mathematic Concepts and Terminologies</span></li>
84-
<li data-link="07-autodiff#differentiable-types"><span>Differentiable Types</span></li>
85-
<li data-link="07-autodiff#forward-derivative-propagation-function"><span>Forward Derivative Propagation Function</span></li>
86-
<li data-link="07-autodiff#backward-derivative-propagation-function"><span>Backward Derivative Propagation Function</span></li>
87-
<li data-link="07-autodiff#builtin-differentiable-functions"><span>Builtin Differentiable Functions</span></li>
88-
<li data-link="07-autodiff#primal-substitute-functions"><span>Primal Substitute Functions</span></li>
89-
<li data-link="07-autodiff#working-with-mixed-differentiable-and-non-differentiable-code"><span>Working with Mixed Differentiable and Non-Differentiable Code</span></li>
90-
<li data-link="07-autodiff#higher-order-differentiation"><span>Higher Order Differentiation</span></li>
91-
<li data-link="07-autodiff#interactions-with-generics-and-interfaces"><span>Interactions with Generics and Interfaces</span></li>
92-
<li data-link="07-autodiff#restrictions-of-automatic-differentiation"><span>Restrictions of Automatic Differentiation</span></li>
84+
<li data-link="08-autodiff#using-automatic-differentiation-in-slang"><span>Using Automatic Differentiation in Slang</span></li>
85+
<li data-link="08-autodiff#mathematic-concepts-and-terminologies"><span>Mathematic Concepts and Terminologies</span></li>
86+
<li data-link="08-autodiff#differentiable-types"><span>Differentiable Types</span></li>
87+
<li data-link="08-autodiff#forward-derivative-propagation-function"><span>Forward Derivative Propagation Function</span></li>
88+
<li data-link="08-autodiff#backward-derivative-propagation-function"><span>Backward Derivative Propagation Function</span></li>
89+
<li data-link="08-autodiff#builtin-differentiable-functions"><span>Builtin Differentiable Functions</span></li>
90+
<li data-link="08-autodiff#primal-substitute-functions"><span>Primal Substitute Functions</span></li>
91+
<li data-link="08-autodiff#working-with-mixed-differentiable-and-non-differentiable-code"><span>Working with Mixed Differentiable and Non-Differentiable Code</span></li>
92+
<li data-link="08-autodiff#higher-order-differentiation"><span>Higher Order Differentiation</span></li>
93+
<li data-link="08-autodiff#interactions-with-generics-and-interfaces"><span>Interactions with Generics and Interfaces</span></li>
94+
<li data-link="08-autodiff#restrictions-of-automatic-differentiation"><span>Restrictions of Automatic Differentiation</span></li>
9395
</ul>
9496
</li>
9597
<li data-link="a1-special-topics"><span>Special Topics</span>

‎examples/cpu-com-example/shader.slang

+4-4
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
// Example using 'NativeString' and COM interface
44

5-
public __global __extern_cpp IDoThings globalDoThings;
5+
export __global __extern_cpp IDoThings globalDoThings;
66

7-
public __extern_cpp NativeString getString(NativeString in)
7+
export __extern_cpp NativeString getString(NativeString in)
88
{
99
return in;
1010
}
@@ -17,12 +17,12 @@ interface IDoThings
1717
void printMessage(NativeString nativeString);
1818
}
1919

20-
public __extern_cpp int calcHash(NativeString text)
20+
export __extern_cpp int calcHash(NativeString text)
2121
{
2222
return globalDoThings.calcHash(text);
2323
}
2424

25-
public __extern_cpp void printMessage(NativeString text)
25+
export __extern_cpp void printMessage(NativeString text)
2626
{
2727
return globalDoThings.printMessage(text);
2828
}

‎source/slang/diff.meta.slang

+1-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ __attributeTarget(FunctionDeclBase)
2626
attribute_syntax [NoDiffThis] : NoDiffThisAttribute;
2727

2828
// A 'none-type' that acts as a run-time sentinel for zero differentials.
29-
public struct NullDifferential : IDifferentiable
29+
export struct NullDifferential : IDifferentiable
3030
{
3131
// for now, we'll use at least one field to make sure the type is non-empty
3232
uint dummy;

0 commit comments

Comments
 (0)