Width vs. Pitch

Although the terms width and pitch are often used interchangeably, their meanings are distinctly different. It is important to understand these meanings, and how to interpret the values that Microsoft Direct3D uses to describe them.

Direct3D uses the SurfaceDescription structure to carry information that describes a surface. Among other things, this structure is defined to contain information about a surface's dimensions, as well as how those dimensions are represented in memory. The structure uses the Height and Width members to describe the logical dimensions of the surface. Both members are measured in pixels. Therefore, the Height and Width values for a 640x480 surface are the same whether it is an 8-bit surface or a 24-bit RGB surface.

When a surface is locked using the Surface.LockRectangle method, and depending on the method overload called, the method returns either a GraphicsStream object or an Array Leave Site filled with the surface data. The pitch of the surface is passed back in the pitch parameter. The value returned in the pitch parameter describes the surface's memory pitch, also called stride. Pitch is the distance, in bytes, between two memory addresses that represent the beginning of one bitmap line and the beginning of the next bitmap line. Because pitch is measured in bytes rather than pixels, a 640x480x8 surface has a very different pitch value than a surface with the same dimensions but a different pixel format. Additionally, the pitch value sometimes reflects bytes that Direct3D has reserved as a cache, so it is not safe to assume that pitch is simply the width multiplied by the number of bytes per pixel. Rather, visualize the difference between width and pitch as shown in the following illustration.

Pitch and width difference

In this figure, the front buffer and back buffer are both 640x480x8, and the cache is 384x480x8.

When accessing surfaces directly, take care to stay within the memory allocated for the dimensions of the surface and stay out of any memory reserved for cache. Also, when locking only a portion of a surface, you must stay within the rectangle you specify when locking the surface. Failure to follow these guidelines will lead to unpredictable results. When rendering directly into surface memory, always use the pitch returned by the Surface.LockRectangle method. Do not assume a pitch based solely on the display mode. If your application works on some display adapters but looks garbled on others, this may be the cause of the problem.

Width vs. Pitch

Related Topics