Getting rid of Tex2D macros

<cat>Material.ShaderReference</cat>
<title>Getting rid of Tex2D macros</title>

# Getting rid of Texture2D/Sample macros
<note>This is a probably little bit too detailed article for beginner people. If this article is too dumb then feel free to edit or nuke it.</note>

In foreseeable future, some macros like all variations of `CreateTexture2D` might become obsolete. In this article you'll see a simple example how can you use Texture2D and SamplerState in your shader code to avoid using `CreateTexture2D` / `Tex2DS` macros. 

## CreateTexture2D to Texture2D, Tex2DS to Sample()
Currently, most shaders use `CreateTexture2D` or `CreateTexture2DWithoutSampler` macros to create a new texture variable, and then `Tex2DS` to sample it inside the main pixel shader function. This is how code usually looks like: 

```cs
// This is an EXAMPLE for creating & sampling Texture2D using macros.
// It's recommended to avoid using such macros as they might break in future.  

PS
{
	#define CUSTOM_MATERIAL_INPUTS

	// Create an input for our Color map, this will show up in material editor. 
	CreateInputTexture2D( Color, Srgb, 8, "", "_color", "Material,10/10", Default3( 1.0, 1.0, 1.0 ) );
	
	// Create a Texture2D variable called "g_tColor" from "Color" input box using CreateTexture2DWithoutSampler macro
	CreateTexture2DWithoutSampler( g_tColor ) < Channel( RGB, Box( Color ), Srgb ); OutputFormat( BC7 ); SrgbRead( true ); >;

	{...}
	
	// Entry point for pixel shader
	float4 MainPs( PixelInput i ) : SV_Target0
	{ 
		// Sample g_tColor texture and store it in a local variable 
		float3 l_tColor = Tex2DS( g_tColor, g_sAniso, i.vTextureCoords.xy ).rgb; 
	
		{...}
	}
}
```

Instead of using `CreateTexture2D`, you can simply create a new Texture2D variable using native HLSL features and add the annotation like in previous example: 

```cs
PS
{
	#define CUSTOM_MATERIAL_INPUTS
	
	// Create an input for our Color map, this will show up in material editor. We still need this.
	CreateInputTexture2D( Color, Srgb, 8, "", "_color", "Material,10/10", Default3( 1.0, 1.0, 1.0 ) );
	
	// Create a Texture2D with required annotation, but now without any macros. Does the same thing as CreateTexture2DWithoutSampler.
	Texture2D g_tColor < Channel( RGB, Box( Color ), Srgb ); OutputFormat( BC7 ); SrgbRead( true ); >; 
	
	{...}
}
```

And then instead of sampling your new Texture2D using `Tex2D`/`Tex2DS` macro, simply use `.Sample( SamplerState, UV )`. In this code example, we will use built-in sampler state `g_sAniso`, so you won't need to create a new sampler. 

```cs
float4 MainPs( PixelInput i ) : SV_Target0
{
	// Sample g_tColor texture and store it in a local variable, but now without using any macros.
	float3 l_tColor = g_tColor.Sample( g_sAniso, v.TextureCoords.xy );

	{...}
}
```

In this code example, we're using `g_sAniso` as a sampler. This is one of built-in samplers that are always available, in most cases that's all what you will need for your shader. If you're looking for a full list of pre-defined samplers, or more details about how sampler states work, check the documentation for [Sampler States in s&box docs](https://docs.facepunch.com/s/sbox-dev/doc/sampler-states-LlJc7ymJkq). 

If you can't find a built-in sampler that meets your requirements, you can create your own. For example, we need a sampler with `AddressU` and `AddressV` set to `CLAMP`, and point filtering enabled. Before the `MainPs` block, declare a new ShaderState variable and set up sampler states in the annotation: 
```cs
SamplerState MyNewSampler < Filter( POINT ); AddressU( CLAMP ); AddressV( CLAMP ); >;
```

In `MainPs` block, you can now sample your Texture2D object using a new sampler like this: 
```cs
float3 l_tColor = g_tColor.Sample( MyNewSampler, v.TextureCoords.xy );
```

## Other examples

If you are using Texture2D arrays, approach to replace macros with native HLSL code will be almost identical. Instead of `CreateTexture2DArray` macro, declare a new object `Texture2DArray name`. To sample a Texture2DArray object, do `.Sample( sampler, uv.xyz )`.

If you're working with Texture2DMS, `CreateTexture2DMS` macro will be just `Texture2DMS<float> name`. Don't forget about including annotations to your Texture2D declarations. 

## But why?

Most IDEs do not understand these macros, and they can make things more confusing for beginners. These macros exist in engine's code since very early days of Source 2 and apparently were required back when it had to compile stuff for DX9, DX11 and OpenGL. 

Instead of fiddling with `CreateTexture2DWithoutSampler`, `Tex2DS` and other macros, you can just use `<object>.Sample( sampler, uv )` function for all types of Texture2Ds, and IDEs will understand it. s&box has a bunch of built-in samplers so in most cases you won't need to create a new sampler state for every shader, but even if you'll need to do this, [it's very easy](https://docs.facepunch.com/s/sbox-dev/doc/sampler-states-LlJc7ymJkq).

Getting rid of Tex2D macros

Account Management

Special Pages

Wiki List

S&box Wiki