Difference between revisions of "Procedural Materials"

From Valve Developer Community
Jump to: navigation, search
m (Conclusion)
m (Added pov notice)
 
(29 intermediate revisions by 16 users not shown)
Line 1: Line 1:
[[Category:Material System]][[Category:Programming]]
+
{{pov}}
=The Basics=
 
  
 
Procedural materials allow you to change the image at the pixel level during runtime.  To create a procedural material you will need 4 things.  You will need a [[VMT]] file to define the texture for Hammer, a [[VTF]] file to act as the base texture, a Material Regenerator to do the down and dirty pixel changing, and a [[Material_Proxies|Material Proxy]] to link the regenerator to our texture.
 
Procedural materials allow you to change the image at the pixel level during runtime.  To create a procedural material you will need 4 things.  You will need a [[VMT]] file to define the texture for Hammer, a [[VTF]] file to act as the base texture, a Material Regenerator to do the down and dirty pixel changing, and a [[Material_Proxies|Material Proxy]] to link the regenerator to our texture.
  
=The VMT File=
+
== The VMT file ==
 
 
 
Let's start by defining our VMT file.  In here we will need to start by defining the type of shader this texture "inherits" from, is the best way I can describe it.  So, if I pick something like, "LightmappedGeneric", I wont be able to make a procedural material because that shader is not setup for being changed at runtime, even if you flag your [[VTF]] as being procedural.  You will just end up with a black image :).  So, for our purposes I would choose something like, "UnlitGeneric".  Another option is "MonitorScreen".  Because these shaders do not limit me to having a static material.
 
Let's start by defining our VMT file.  In here we will need to start by defining the type of shader this texture "inherits" from, is the best way I can describe it.  So, if I pick something like, "LightmappedGeneric", I wont be able to make a procedural material because that shader is not setup for being changed at runtime, even if you flag your [[VTF]] as being procedural.  You will just end up with a black image :).  So, for our purposes I would choose something like, "UnlitGeneric".  Another option is "MonitorScreen".  Because these shaders do not limit me to having a static material.
  
 
The next step is to choose a basetexture.  More than anything this texture is there for purposes of having a canvas to paint on.  You can always change it at runtime to increase its size...but I'm going to try and keep this as simple as possible.  So for now, just come up with a name for your texture, we will actually create it in the next step.
 
The next step is to choose a basetexture.  More than anything this texture is there for purposes of having a canvas to paint on.  You can always change it at runtime to increase its size...but I'm going to try and keep this as simple as possible.  So for now, just come up with a name for your texture, we will actually create it in the next step.
  
After choosing a base texture, we need to come up with our proxy name.  We will define it later, but for now just come up with something creative.  PixelRenderer, excellent choice.  Okay, so now your [[VMT]] file should look something like this...
+
After choosing a base texture, we need to come up with our proxy name.  We will define it later, but for now just come up with something creative.  PixelRenderer, excellent choice.  Now your [[VMT]] file should look something like this.
  
 
<pre>
 
<pre>
Line 16: Line 14:
 
{
 
{
 
"$basetexture" "nicks_materials/prodscreen"
 
"$basetexture" "nicks_materials/prodscreen"
 +
"$translucent" 1
 
 
 
"Proxies"
 
"Proxies"
Line 26: Line 25:
 
</pre>
 
</pre>
  
=The VTF File=
+
== The VTF file ==
 
 
 
I'm going to recommend you use [[VTFEdit]] for this, because it's a great program.  Start off by opening up your Paint program of choice.  I'm not rich so I'll stick with MS Paint.  Go ahead and make it 512x512, it doesn't need to be anything special...a red background with the words "Procedural Screen" work wonderfully.  Now, in [[VTFEdit]], you will need to import your newly created texture.
 
I'm going to recommend you use [[VTFEdit]] for this, because it's a great program.  Start off by opening up your Paint program of choice.  I'm not rich so I'll stick with MS Paint.  Go ahead and make it 512x512, it doesn't need to be anything special...a red background with the words "Procedural Screen" work wonderfully.  Now, in [[VTFEdit]], you will need to import your newly created texture.
  
 
Here is what mine looks like.
 
Here is what mine looks like.
  
[[Image:vtfedit_import_options.png|Import Texture Options]]
+
[[Image:vtfedit_import_options.png|center|Import Texture Options]]
  
 
So, after you are finished importing we need to set some flags.  These flags tell us an abundance of information about the image.
 
So, after you are finished importing we need to set some flags.  These flags tell us an abundance of information about the image.
  
{|
+
;<code>No Compression</code>
| <code>No Compression</code> || This one is chosen for us because, we chose a non-compressed format for our image.
+
:This one is chosen for us because, we chose a non-compressed format for our image.
|-
+
;<code>No Mipmap</code>
| <code>No Mipmap</code> || Mip maps create problems when dealing with the LOD system and a dynamic image.  If we change the pixels in the image, the mip maps would need to be regenerated, and if you don't you will end up with random memory spew obfuscating parts of our beautiful procedural image.
+
:Mip maps create problems when dealing with the LOD system and a dynamic image.  If we change the pixels in the image, the mip maps would need to be regenerated, and if you don't you will end up with random memory spew obfuscating parts of our beautiful procedural image.
|-
+
;<code>No Level of Detail</code>
| <code>No Level of Detail</code> || We don't want our image futzed the further away we get.
+
:We don't want our image futzed the further away we get.
|-
+
;<code>Procedural</code>
| <code>Procedural</code> || This one tells source that our base texture can change at runtime, without it everything else means nothing.
+
:This one tells source that our base texture can change at runtime, without it everything else means nothing.
|-
 
|}
 
  
 
So in [[VTFEdit]], it looks something like this:
 
So in [[VTFEdit]], it looks something like this:
  
[[Image:vtfedit_screen.png|My Texture]]
+
[[Image:vtfedit_screen.png|center|My Texture]]
 
 
=The Material Regenerator=
 
  
 +
== The material regenerator ==
 
Now, comes the part you've all been waiting for...and probably skipped right down to.  So lets get to it.  This is the brains of the operation, the meat of the can, the...you get the idea.  Start out by defining our class.  It will need to inherit from [[ITextureRegenerator]], because that's the regenerator interface.  There are 2 methods that we will need to overwrite for this to work.  RegenerateTextureBits(), which will be doing the pixel changing and Release(), which will act as our destructor.
 
Now, comes the part you've all been waiting for...and probably skipped right down to.  So lets get to it.  This is the brains of the operation, the meat of the can, the...you get the idea.  Start out by defining our class.  It will need to inherit from [[ITextureRegenerator]], because that's the regenerator interface.  There are 2 methods that we will need to overwrite for this to work.  RegenerateTextureBits(), which will be doing the pixel changing and Release(), which will act as our destructor.
  
Line 59: Line 54:
 
{
 
{
 
public:
 
public:
CProceduralRegenerator( void );
+
CProceduralRegenerator( void ) {};
 
virtual void RegenerateTextureBits( ITexture *pTexture, IVTFTexture *pVTFTexture, Rect_t *pSubRect );
 
virtual void RegenerateTextureBits( ITexture *pTexture, IVTFTexture *pVTFTexture, Rect_t *pSubRect );
 
virtual void Release( void );
 
virtual void Release( void );
}
+
};
 
</pre>
 
</pre>
  
Line 70: Line 65:
 
void CProceduralRegenerator::RegenerateTextureBits( ITexture *pTexture, IVTFTexture *pVTFTexture, Rect_t *pSubRect )
 
void CProceduralRegenerator::RegenerateTextureBits( ITexture *pTexture, IVTFTexture *pVTFTexture, Rect_t *pSubRect )
 
{
 
{
// Gets a pointer to the start of the texture memory.
+
CPixelWriter pixelWriter;
unsigned char *imageData = pVTFTexture->ImageData();
+
pixelWriter.SetPixelMemory( pVTFTexture->Format(),  
 
+
pVTFTexture->ImageData( 0, 0, 0 ), pVTFTexture->RowSizeInBytes( 0 ) );
//NOTE: the format of any texture using the IVTFTexture interface appears to be in BGRX8888 everytime
 
//      despite what you set it at in the VTF, so keep that in mind.
 
 
 
// Lets place our texture width and height in local vars.
 
int height = pVTFTexture->Height();
 
int width = pVTFTexture->Width();
 
  
        // Define vars to hold our position in the texture
+
// Now upload the part we've been asked for
 +
int xmax = pSubRect->x + pSubRect->width;
 +
int ymax = pSubRect->y + pSubRect->height;
 
int x, y;
 
int x, y;
  
// Now, lets have some fun with our image.
+
for( y = pSubRect->y; y < ymax; ++y )
// This could be optimized...but I'm going for readability
 
for( y = 0; y < height; y++ )
 
 
{
 
{
for( x = 0; x < width; x++ )
+
pixelWriter.Seek( pSubRect->x, y );
 +
 
 +
for( x=pSubRect->x; x < xmax; ++x )
 
{
 
{
int texture_offset = 4 * ( x + y * width ); // This calculates our position in memory given the x and y
+
pixelWriter.WritePixel( y%256, 0, 0, 255 );
    // position in the image
 
 
 
imageData[texture_offset]    = 0;        // Blue Channel
 
imageData[texture_offset + 1] = 0;        // Green Channel
 
imageData[texture_offset + 2] = y % 256;  // Red Channel
 
imageData[texture_offset + 3] = 255;     // 100% Alpha (Opaque)
 
 
}
 
}
 
}
 
}
}
+
}</pre>
</pre>
 
  
Also define your Release() method, and delete anything you create.
+
Also define your <code>Release()</code> method, and delete anything you create.
  
 
<pre>
 
<pre>
Line 110: Line 94:
 
</pre>
 
</pre>
  
=The Material Proxy=
+
== The material proxy ==
 
+
Here we will connect our regenerator to our texture. There is already an article on the [[Material_Proxies|Material Proxy]] so I wont go into too much detail. But start out by defining your material proxy class. It should look something like this:
Here we will connect our regenerator to our texture. There is already an article on the [[Material_Proxies|Material Proxy]] so I wont go into too much detail. But start out by defining your material proxy class. It should look something like this:
 
  
 
<pre>
 
<pre>
Line 123: Line 106:
 
virtual void OnBind( void *pC_BaseEntity );
 
virtual void OnBind( void *pC_BaseEntity );
 
virtual void Release( void ) { delete this; }
 
virtual void Release( void ) { delete this; }
 +
virtual IMaterial *GetMaterial() { return m_pTextureVar->GetOwningMaterial(); }
  
 
private:
 
private:
Line 142: Line 126:
 
</pre>
 
</pre>
  
Our destructor will be called when release is called note the { delete this; } inside the class definition of the method Release(). Here we will disconnect our regenerator from the texture.
+
Our destructor will be called when release is called note the { delete this; } inside the class definition of the method <code>Release()</code>. Here we will disconnect our regenerator from the texture.
  
 
<pre>
 
<pre>
Line 154: Line 138:
 
</pre>
 
</pre>
  
The Init method is used to initialize everything during the precache period of loading.
+
The <code>Init</code> method is used to initialize everything during the <code>precache</code> period of loading.
  
 
<pre>
 
<pre>
Line 179: Line 163:
 
</pre>
 
</pre>
  
The OnBind() method is called for lots of reasons, read the [[Material_Proxies|Material Proxy]] article for more info.  But think of this as our refresh method.  We use this to tell the regenerator it needs to update the bits, which happens every time a new frame is rendered. The Download() method is how we tell the regenerator to redraw. You have the option of passing in a sub-rectangle of space you want to change, but all it does is send that info to your regenerator which you can use or ignore. If you don't give it a rectangle it sends a rectangle matching the full dimensions of our texture.
+
The <code>OnBind()</code> method is called for lots of reasons, read the [[Material_Proxies|Material Proxy]] article for more info.  But think of this as our refresh method.  We use this to tell the regenerator it needs to update the bits, which happens every time a new frame is rendered. The Download() method is how we tell the regenerator to redraw. You have the option of passing in a sub-rectangle of space you want to change, but all it does is send that info to your regenerator which you can use or ignore. If you don't give it a rectangle it sends a rectangle matching the full dimensions of our texture.
  
 
<pre>
 
<pre>
Line 196: Line 180:
 
This exposes our proxy to the outside world and allows Source to match up the proxy class with the name listed as the proxy in the [[VMT]] file.
 
This exposes our proxy to the outside world and allows Source to match up the proxy class with the name listed as the proxy in the [[VMT]] file.
  
<pre>
+
EXPOSE_INTERFACE( CProceduralProxy, IMaterialProxy, "PixelRenderer" IMATERIAL_PROXY_INTERFACE_VERSION );
EXPOSE_INTERFACE( CProceduralProxy, IMaterialProxy, "PixelRenderer", IMATERIAL_PROXY_INTERFACE_VERSION );
+
 
</pre>
+
== Conclusion ==
 +
This brings us full circle, and now our texture should bend to the will of our imagination on what to render at runtime.  So now it's up to you to find a use for this feature.  I'm currently working on an AVI renderer to be used in game, for various movie playing applications.  You don't need to edit much of the code above to add this feature to your own games.  For more information, you should checkout [[AVIKit]], it has a very simple interface for doing just this.  For more information about playing movies in Source, see [[AVI Materials]].
 +
 
 +
Here is an example of Red vs. Blue: Episode 1 playing in HL2.
  
=Conclusion=
+
[[Image:Proctex1.jpg|thumb|left|300px|Before...]][[Image:Proctex2.jpg|thumb|left|300px|...and after.]]
  
This brings us full circle, and now our texture should bend to the will of our imagination on what to render at runtime.  So now it's up to you to find a use for this feature.  I'm currently working on an AVI renderer to be used in game, for various movie playing applications.  You don't need to edit much of the code above to add this feature to your own games.  For more information, you should checkout [[AVIKit]], it has a very simple interface for doing just this.
+
[[Category:Material System]]
 +
[[Category:Programming]]

Latest revision as of 11:41, 19 June 2017


Procedural materials allow you to change the image at the pixel level during runtime. To create a procedural material you will need 4 things. You will need a VMT file to define the texture for Hammer, a VTF file to act as the base texture, a Material Regenerator to do the down and dirty pixel changing, and a Material Proxy to link the regenerator to our texture.

The VMT file

Let's start by defining our VMT file. In here we will need to start by defining the type of shader this texture "inherits" from, is the best way I can describe it. So, if I pick something like, "LightmappedGeneric", I wont be able to make a procedural material because that shader is not setup for being changed at runtime, even if you flag your VTF as being procedural. You will just end up with a black image :). So, for our purposes I would choose something like, "UnlitGeneric". Another option is "MonitorScreen". Because these shaders do not limit me to having a static material.

The next step is to choose a basetexture. More than anything this texture is there for purposes of having a canvas to paint on. You can always change it at runtime to increase its size...but I'm going to try and keep this as simple as possible. So for now, just come up with a name for your texture, we will actually create it in the next step.

After choosing a base texture, we need to come up with our proxy name. We will define it later, but for now just come up with something creative. PixelRenderer, excellent choice. Now your VMT file should look something like this.

"UnlitGeneric"
{
	"$basetexture" "nicks_materials/prodscreen"
	"$translucent" 1
	
	"Proxies"
	{
		"PixelRenderer"
		{
		}
	}
}

The VTF file

I'm going to recommend you use VTFEdit for this, because it's a great program. Start off by opening up your Paint program of choice. I'm not rich so I'll stick with MS Paint. Go ahead and make it 512x512, it doesn't need to be anything special...a red background with the words "Procedural Screen" work wonderfully. Now, in VTFEdit, you will need to import your newly created texture.

Here is what mine looks like.

Import Texture Options

So, after you are finished importing we need to set some flags. These flags tell us an abundance of information about the image.

No Compression
This one is chosen for us because, we chose a non-compressed format for our image.
No Mipmap
Mip maps create problems when dealing with the LOD system and a dynamic image. If we change the pixels in the image, the mip maps would need to be regenerated, and if you don't you will end up with random memory spew obfuscating parts of our beautiful procedural image.
No Level of Detail
We don't want our image futzed the further away we get.
Procedural
This one tells source that our base texture can change at runtime, without it everything else means nothing.

So in VTFEdit, it looks something like this:

My Texture

The material regenerator

Now, comes the part you've all been waiting for...and probably skipped right down to. So lets get to it. This is the brains of the operation, the meat of the can, the...you get the idea. Start out by defining our class. It will need to inherit from ITextureRegenerator, because that's the regenerator interface. There are 2 methods that we will need to overwrite for this to work. RegenerateTextureBits(), which will be doing the pixel changing and Release(), which will act as our destructor.

class CProceduralRegenerator : public ITextureRegenerator
{
public:
	CProceduralRegenerator( void ) {};
	virtual void RegenerateTextureBits( ITexture *pTexture, IVTFTexture *pVTFTexture, Rect_t *pSubRect );
	virtual void Release( void );
};

Now we need to regenerate our texture bits.

void CProceduralRegenerator::RegenerateTextureBits( ITexture *pTexture, IVTFTexture *pVTFTexture, Rect_t *pSubRect )
{
	CPixelWriter pixelWriter;
	pixelWriter.SetPixelMemory( pVTFTexture->Format(), 
		pVTFTexture->ImageData( 0, 0, 0 ), pVTFTexture->RowSizeInBytes( 0 ) );

	// Now upload the part we've been asked for
	int xmax = pSubRect->x + pSubRect->width;
	int ymax = pSubRect->y + pSubRect->height;
	int x, y;

	for( y = pSubRect->y; y < ymax; ++y )
	{
		pixelWriter.Seek( pSubRect->x, y );

		for( x=pSubRect->x; x < xmax; ++x )
		{
			pixelWriter.WritePixel( y%256, 0, 0, 255 );
		}
	}
}

Also define your Release() method, and delete anything you create.

void CProceduralRegenerator::Release()
{
	//delete stuff
}

The material proxy

Here we will connect our regenerator to our texture. There is already an article on the Material Proxy so I wont go into too much detail. But start out by defining your material proxy class. It should look something like this:

class CProceduralProxy: public IMaterialProxy
{
public:
	CProceduralProxy();
	virtual ~CProceduralProxy();
	virtual bool Init( IMaterial* pMaterial, KeyValues *pKeyValues );
	virtual void OnBind( void *pC_BaseEntity );
	virtual void Release( void ) { delete this; }
	virtual IMaterial *GetMaterial() { return m_pTextureVar->GetOwningMaterial(); }

private:
	IMaterialVar		*m_pTextureVar;   // The material variable
	ITexture		*m_pTexture;      // The texture
	ITextureRegenerator	*m_pTextureRegen; // The regenerator
};

Here's a basic constructor to just set all our pointers to NULL.

CProceduralProxy::CProceduralProxy()
{
	m_pTextureVar = NULL;
	m_pTexture = NULL;
	m_pTextureRegen = NULL;
}

Our destructor will be called when release is called note the { delete this; } inside the class definition of the method Release(). Here we will disconnect our regenerator from the texture.

CProceduralProxy::~CProceduralProxy()
{
	if (m_pTexture != NULL)
	{
		m_pTexture->SetTextureRegenerator( NULL );
	}
}

The Init method is used to initialize everything during the precache period of loading.

bool CProceduralProxy::Init( IMaterial *pMaterial, KeyValues *pKeyValues )
{
	bool found;
	
	m_pTextureVar = pMaterial->FindVar("$basetexture", &found, false);  // Get a reference to our base texture variable
	if( !found )
	{
		m_pTextureVar = NULL;
		return false;
	}

	m_pTexture = m_pTextureVar->GetTextureValue();  // Now grab a ref to the actual texture
	if (m_pTexture != NULL)
	{
		m_pTextureRegen = new CProceduralRegenerator( );  // Here we create our regenerator
		m_pTexture->SetTextureRegenerator(m_pTextureRegen); // And here we attach it to the texture.
	}

	return true;
}

The OnBind() method is called for lots of reasons, read the Material Proxy article for more info. But think of this as our refresh method. We use this to tell the regenerator it needs to update the bits, which happens every time a new frame is rendered. The Download() method is how we tell the regenerator to redraw. You have the option of passing in a sub-rectangle of space you want to change, but all it does is send that info to your regenerator which you can use or ignore. If you don't give it a rectangle it sends a rectangle matching the full dimensions of our texture.

void CProceduralProxy::OnBind( void *pEntity )
{
	if( !m_pTexture )  // Make sure we have a texture
		return;

	if(!m_pTextureVar->IsTexture())  // Make sure it is a texture
		return;

	m_pTexture->Download(); // Force the regenerator to redraw
}

This exposes our proxy to the outside world and allows Source to match up the proxy class with the name listed as the proxy in the VMT file.

EXPOSE_INTERFACE( CProceduralProxy, IMaterialProxy, "PixelRenderer" IMATERIAL_PROXY_INTERFACE_VERSION );

Conclusion

This brings us full circle, and now our texture should bend to the will of our imagination on what to render at runtime. So now it's up to you to find a use for this feature. I'm currently working on an AVI renderer to be used in game, for various movie playing applications. You don't need to edit much of the code above to add this feature to your own games. For more information, you should checkout AVIKit, it has a very simple interface for doing just this. For more information about playing movies in Source, see AVI Materials.

Here is an example of Red vs. Blue: Episode 1 playing in HL2.

Before...
...and after.