DOC: EngPlgBlt for Rotating a Bitmap Surface

• Microsoft Win32 Device Driver Kit (DDK) for Windows NT, version 3.51

SUMMARY

There is an error in the online documentation for the EngPlgBlt function, and it is quite un-intuitive. This function is used for both Win32 display drivers and Win32 printer drivers.

MORE INFORMATION

The parameter "pptfxDest" that defines the parallelogram of the destination surface is actually a pointer to an array of type POINTFIX (not POINTFX) as defined in %DDK%\inc\winddi.h:

   typedef LONG FIX;
   typedef struct  _POINTFIX
   {
       FIX   x;
       FIX   y;
   } POINTFIX, *PPOINTFIX;

NOTE: If the Destination surface is less than the Source surface, the image will shrink and rotate accordingly. If the Destination surface is greater than the Source surface, the image will also stretch and rotate accordingly. Otherwise, the surface will just rotate accordingly.

SAMPLE

//////////////////////////////////////////////////////////////////////////
//
// This routine simply rotates a surface's bitmap 90 degrees to the right.
// Note: DISPDBG() is from %DDK%\src\video\displays\vga\debug.*
//
   BOOL
   RotateSurface(
      SURFOBJ *psoSource
      )
   {
       PPDEV       ppdev;
       HSURF       hSurf;
       SURFOBJ    *psoDest;
       SIZEL       sizl;
       RECTL       rclSrc;
       POINTFIX    pfxDest[3];

       //
       // get the pointer to our DEVDATA structure
       //
       ppdev = (PPDEV)psoSource->dhpdev;

       //
       // create the rotated bitmap
       //
       sizl.cx = psoSource->sizlBitmap.cy;
       sizl.cy = psoSource->sizlBitmap.cx;

       if ((hSurf = (HSURF)EngCreateBitmap(
               sizl,
               sizl.cx,
                  psoSource->iBitmapFormat,
                  psoSource->fjBitmap,
                  NULL)) == NULL )
      {
         DISPDBG((0, "EngCreateBitmap FAILED; GetLastError() = %d\n",
   GetLastError() ));
            return(FALSE);
      }

       if (!EngAssociateSurface(
         hSurf,
            ppdev->hdevEng, // Note: we must have stored this earlier
            0L) )
      {
         DISPDBG((0, "EngAssociateSurface FAILED; GetLastError() = %d\n",
   GetLastError() ));
         EngDeleteSurface(hSurf);
            return(FALSE);
      }

       //
       // setup the destination pointfx array
       //
       pfxDest[0].x = sizl.cx << 4; // A
       pfxDest[0].y = 0;
       pfxDest[1].x = sizl.cx << 4;    // B
       pfxDest[1].y = sizl.cy << 4;
       pfxDest[2].x = 0;         // C
       pfxDest[2].y = 0;

       //
       // setup the source rectangle
       //
       rclSrc.top    = 0;
       rclSrc.left   = 0;
       rclSrc.bottom = psoSource->sizlBitmap.cy;
       rclSrc.right  = psoSource->sizlBitmap.cx;

       //
       // rotate the original bitmap 90 degrees to the right onto the new
   bitmap
       //
       if (!EngPlgBlt(
         psoDest,
            psoSource,
            NULL, NULL, NULL, NULL, NULL,
               &pfxDest[0],
               &rclSrc,
               NULL,
               HALFTONE ))
       {
            DISPDBG((0, "EngPlgBlt FAILED; GetLastError() = %d\n",
   GetLastError() ));
            EngDeleteSurface(hSurf);
            return(FALSE);
       }

       //
       // you now have your rotated bitmap in psoDest until you delete it.
       //

       EngDeleteSurface(hSurf);

       return(TRUE);
   }

REFERENCES

For additional information on the iMode parameter, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q140674
   TITLE     : DOCERR: Incorrect iModes Parameter to DDI StretchBlt
               Functions