Although the terms widthand pitchare often used informally, they have very important, and distinctly different, meanings. As a result, you should understand the meanings for each, and how to interpret the values that Microsoft® Direct3D® uses to describe them.

Direct3D Mobile uses the D3DMSURFACE_DESCstructure to carry information describing 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 Heightand Widthmembers to describe the logical dimensions of the surface. Both members are measured in pixels. Therefore, the Heightand Widthvalues for a 640×480 surface are the same whether it is an 8-bit surface or a 24-bit RGB surface.

When you lock a surface using the IDirect3DMobileSurface::LockRectmethod, the method fills in a D3DMLOCKED_RECTstructure that contains the pitch of the surface and a pointer to the locked bits. The value in the Pitchmember 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 640×480×8 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 Mobile 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.

Pitch values are only useful when you are directly accessing surface memory. For example, after calling the LockRectmethod, the pBitsmember of the associated D3DMLOCKED_RECTstructure contains the address of the top-left pixel of the locked area of the surface, and the Pitchmember is the surface pitch. You access pixels horizontally by incrementing or decrementing the surface pointer by the number of bytes per pixel, and you move up or down by adding the pitch value to, or subtracting it from, the current surface pointer.

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. Additionally, when you lock only a portion of a surface, you must stay within the rectangle you specify when locking the surface. Failing to follow these guidelines will have unpredictable results. When rendering directly into surface memory, always use the pitch returned by the LockRectmethod. 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.

See Also