Texture creation and texture manager

Raw data update interfaces

The fastest interface to use is the one that accepts a reference to raw data. This data can either be newly created in CPU memory, or data that is extracted from an existing MTexture or MRenderTarget.

Whether newly created or not, it is important to use the appropriate row pitch as the row pitch may not be equal to the length of a texture row. Row padding concerns mainly affect textures that are created using the DirectX API. For example, if the data is extracted from an existing texture, the row pitch information extracted via the MTexture::rawData() method should be used. For new raw data, the row pitch information can additionally be computed based on the bytes-per-pixel method (MTexture::bytesPerPixel()) and the width for a texture.

If the data is being extracted from a target via MRenderTarget::rawData(), the target may or may not be a texture and it is thus best to use the returned row pitch value. Note that a target (MRenderTarget) can be created with data from an on screen buffer (for example, a DirectX11 SwapChain) via the MRenderTargetManager::acquireRenderTargetFromScreen() method. A proper row pitch value should still be used in this case.

The basic cost of writing new data is the upload of CPU data to GPU texture. This should not be a “blocking” operation, meaning no data is read back from the GPU. For example, for OpenGL writers, the upload can be regarded as the equivalent of calling glTexSubImage*().

Reading back from an existing texture is blocking, since the memory needs to be mapped back to CPU memory from GPU memory.

MImage update interface

Data from an existing MImage can also be used to update an existing MTexture. It is the responsibility of the caller to ensure that the format of the texture matches that of the MImage. This is currently 4-channel, 8 bytes-per-channel RGBA color. The bytesPerPixel() method can be used to check for a match.

Using the MImage interface requires mapping GPU memory to the CPU, updating it and then mapping it back to the GPU.

“Backdoor” updating via GPU handle

As GPU resource handles (MTexture::resourceHandle()) are available, it is also possible to perform the update using these handles. For example, GPU to GPU resource memory transfers are not exposed in the API, but can be performed using the raw resource handles.

It is strongly recommended that no format change or data size occurs via operations on this handle, as the resource is owned by the internal renderer, and would never know that any of these attributes have been modified.

Texture update examples

The following diagram illustrates the interaction between the various update possibilities.

Figure 29: On the left, an MImage could be used to upload new context to the MTexture. Part of this data is mapped back to the CPU and the new data copied over. The flow of data shown above the MTexture illustrates possible reading back of the raw data, and the possible updating of the texture using raw data. The top right shows that the raw data can also be read from an offscreen render target. The bottom right illustrates the ability to access the GPU handle in order to update the texture.

The following is an example which reads back the raw pixel data from a texture, inverts the pixels and then writes the data back to the texture. The texture here is assumed to have a format of 24-bit fixed point RGBA.

// Get the texture description from the texture 
MHWRender::MTextureDescription desc;
texture->textureDescription(desc);
unsigned int bpp = texture->bytesPerPixel();

// This code happens to only work with fixed-bit 8888 RGBA
//
if (bpp == 4 && 
	(desc.fFormat == MHWRender::kR8G8B8A8_UNORM ||
	 desc.fFormat == MHWRender::kB8G8R8A8))
{
	int rowPitch = 0;
	int slicePitch = 0;
	bool generateMipMaps = true;

	// Extract out the raw data from the texture. Also gets the row and slice pitch
	// The assumption is that this is 2D texture so slicePitch would be 1.
	// A GPU->CPU transfer of data will occur.
	unsigned char* pixelData = (unsigned char *)texture->rawData(rowPitch, slicePitch);
	unsigned char* val = NULL;
	if (pixelData && rowPitch > 0 && slicePitch > 0)
	{
		// Do some example operation: invert the pixel values (255-value)
		for (unsigned int i=0; i<desc.fHeight; i++)
		{
			val = pixelData + (i*rowPitch);
			for (unsigned int j=0; j<desc.fWidth*4; j++)
			{
				*val = 255 - *val;
				val++;
			}
		}
		// Update the texture. A CPU to GPU transfer of data will occur
		texture->update(pixelData, generateMipMaps, rowPitch);
	}
	delete [] pixelData;
}

The sample plug-in hwAPITextureTest uses the above inversion code to update textures read from disk, blits the result to the screen, and then extracts raw data from an on screen target to transfer back to a texture. The texture is then written to disk.

The sample plug-in viewImageBlitOverride demonstrates the update of a color texture for each refresh of a render override (MRenderOverride).

Blitting depth textures

The simplest way to transfer the contents of a depth texture to an output target is to use a shader (MShaderInstance).

A sample shader called mayaBlitColorDepth has been provided in effects file format. The shader can be acquired via the shader manager. The shader currently shows the transfer from a R32 input texture containing normalized values to depth output.

As with color textures, the co-ordinate target system is from top-to-bottom. The sample shader performs the vertical flip in V as appropriate. Plug-in writers can choose to create their textures with whatever convention they choose and perform the V flip to be consistent.

This shader is used in the viewImageBlitOverride plug-in example.