Procedural Materials

From Valve Developer Community
Revision as of 10:51, 24 August 2005 by ZeroDegrez (talk | contribs) (No need for a material regenerator article, mine pretty much covers everything.)
Jump to: navigation, search

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 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. Okay, so now your VMT file should look something like this...

	"$basetexture" "nicks_materials/prodscreen"

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, 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
	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 )
	// Gets a pointer to the start of the texture memory.
	unsigned char *imageData = pVTFTexture->ImageData();

	//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
	int x, y;

	// Now, lets have some fun with our image.
	// This could be optimized...but I'm going for readability
	for( y = 0; y < height; y++ )
		for( x = 0; x < width; x++ )
			int texture_offset = 4 * ( x + y * width ); // This calculates our position in memory given the x and y
								    // 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)

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
	virtual ~CProceduralProxy();
	virtual bool Init( IMaterial* pMaterial, KeyValues *pKeyValues );
	virtual void OnBind( void *pC_BaseEntity );
	virtual void Release( void ) { delete this; }

	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.

	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.

	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

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

	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.



This brings us full circle, and now our texture should bend to the will of our imagenation 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.