Previous
Microsoft Packages
Index
Next
| Package com.ms.com.directX |
Previous |
Microsoft Packages |
Index |
Next |
Applications use the methods of the ddSurface class to create DirectDraw surface objects and work with system-level variables.
public class ddSurface implements IddSurface
{
public void InternalSetObject(IUnknown lpdds);
public IUnknown InternalGetObject();
public void AddAttachedSurface(ddSurface ddS);
public void AddOverlayDirtyRect(Rect r);
public int Blt(Rect dest, ddSurface ddS, Rect src, int flags);
public void BltBatch(ddBltBatch buf, int d1, int d2);
public int BltFast(int dx, int dy, ddSurface ddS, Rect src, int trans);
public void DeleteAttachedSurface(int flags, IddSurface ddS);
public void EnumAttachedSurfaces(IUnknown args, IEnumSurfacesCallback fn);
public void EnumOverlayZOrders(int flags, IUnknown args, IEnumZOrdersCallback fn);
public void Flip(ddSurface ddS, int flags);
public void Flush(Rect r, ddSurfaceDesc d, int flags, int hnd, int[] memory);
public ddSurface GetAttachedSurface(int caps);
public int GetBltStatus(int flags);
public int GetCaps();
public ddClipper GetClipper();
public void GetColorKey(int flags, ddColorKey val);
public int GetDC();
public int GetFlipStatus(int flags);
public int GetOverlayPositionX();
public int GetOverlayPositionY();
public ddPalette GetPalette();
public void GetPixelFormat(ddPixelFormat pf);
public void GetSurfaceDesc(ddSurfaceDesc surface);
public void Initialize(dDraw dd, ddSurfaceDesc surface);
public int IsLost();
public void Lock(Rect r, ddSurfaceDesc d, int flags, int hnd, int[] memory);
public void ReleaseDC(int hdc);
public int Restore();
public void SetClipper(ddClipper val);
public void SetColorKey(int flags, ddColorKey val);
public void SetOverlayPosition(int x, int y);
public void SetPalette(ddPalette ddp);
public void Unlock(ddSurfaceDesc data);
public void UpdateOverlay(Rect r, ddSurface ddS, Rect d, int flags);
public void UpdateOverlayDisplay(int flags);
public void UpdateOverlayZOrder(int flags, ddSurface ddS);
public IUnknown GetDDInterface();
public void PageLock(int flags);
public void PageUnlock(int flags);
public void CopyBitmap(dBitmap val, int cx, int cy, int dx, int dy);
}
The methods can be organized into the following groups:
| Allocating memory | Initialize |
| IsLost | |
| Restore | |
| Attaching surfaces | AddAttachedSurface |
| DeleteAttachedSurface | |
| EnumAttachedSurfaces | |
| GetAttachedSurface | |
| Blitting | Blt |
| BltBatch | |
| BltFast | |
| Color keys | GetColorKey |
| SetColorKey | |
| Device contexts | GetDC |
| ReleaseDC | |
| Flipping surfaces | Flip |
| Locking surfaces | Flush |
| Lock | |
| PageLock | |
| PageUnlock | |
| Unlock | |
| Miscellaneous | GetDDInterface |
| CopyBitmap | |
| Overlays | AddOverlayDirtyRect |
| EnumOverlayZOrders | |
| GetOverlayPositionX | |
| GetOverlayPositionY | |
| SetOverlayPosition | |
| UpdateOverlay | |
| UpdateOverlayDisplay | |
| UpdateOverlayZOrder | |
| Status | GetBltStatus |
| GetFlipStatus | |
| Surface capabilities | GetCaps |
| Surface clipper | GetClipper |
| SetClipper | |
| Surface description | GetPixelFormat |
| GetSurfaceDesc | |
| Surface palettes | GetPalette |
| SetPalette |
public void AddAttachedSurface(ddSurface ddS);Attaches a surface to another surface.
Return Value:
No return value.
Parameter Description ddS The ddSurface object to attach. See Also: DeleteAttachedSurface, EnumAttachedSurfaces, Flip
public void AddOverlayDirtyRect(Rect r);Builds the list of the rectangles that need to be updated the next time the UpdateOverlayDisplay method is called.
Return Value:
No return value.
Parameter Description r The Rect object that needs to be updated. Remarks:
This method is used for the software implementation. It is not needed if the overlay support is provided by the hardware.
See Also: UpdateOverlayDisplay
public int Blt(Rect dest, ddSurface ddS, Rect src, int flags);Performs a bit block transfer.
Return Value:
Returns TRUE.
Parameter Description dest A Rect object that defines the upper-left and lower-right points of the rectangle on the destination surface to be blitted to. ddS The ddSurface object that is the source for the blit operation. src A Rect object that defines the upper-left and lower-right points of the rectangle on the source surface to be blitted from. flags One or more of these values:
DDBLT_ALPHADEST DDBLT_ASYNC DDBLT_ALPHADESTNEG DDBLT_KEYDEST DDBLT_ALPHASRC DDBLT_KEYSRC DDBLT_ALPHASRCNEG DDBLT_WAIT Remarks:
This method is capable of synchronous or asynchronous blits, either display memory to display memory, display memory to system memory, system memory to display memory, or system memory to system memory. The blits can be performed by using z-information, alpha information, source color keys, and destination color keys. Arbitrary stretching or shrinking will be performed if the source and destination rectangles are not the same size.
Typically, Blt returns immediately with an error if the blitter is busy and the blit could not be set up. The DDBLT_WAIT flag can alter this behavior so that the method will either wait until the blit can be set up or another error occurs before it returns.
public void BltBatch(ddBltBatch buf, int d1, int d2);Performs a sequence of Blt operations from several sources to a single destination. This method is currently only a stub; it has not yet been implemented.
Return Value:
No return value.
Parameter Description buf The first ddBltBatch object that defines the parameters for the blit operations. d1 The number of blit operations to be performed. d2 Reserved; must be 0.
public int BltFast(int dx, int dy, ddSurface ddS, Rect src, int trans);Performs a source copy blit or transparent blit by using a source color key or destination color key. This method always attempts an asynchronous blit if it is supported by the hardware.
Return Value:
Returns TRUE.
Parameter Description dx and dy The x- and y-coordinates to blit to on the destination surface. ddS The ddSurface object that is the source for the blit operation. src The Rect object that defines the upper-left and lower-right points of the rectangle on the source surface to be blitted from. trans One value of DDBLTFAST_ type, specifying the type of transfer. Remarks:
This method works only on display memory surfaces and cannot clip when blitting. The software implementation of BltFast is 10 percent faster than the Blt method. However, there is no speed difference between the two if display hardware is being used.
Typically, BltFast returns immediately with an error if the blitter is busy and the blit cannot be set up. You can use the DDBLTFAST_WAIT flag, however, if you want this method to not return until either the blit can be set up or another error occurs.
public void DeleteAttachedSurface(int flags, IddSurface ddS);Detaches two attached surfaces. The detached surface is not released.
Return Value:
No return value.
Parameter Description flags Reserved; must be 0. ddS The ddSurface object to detach. If this parameter is null, all attached surfaces are detached. See Also: Flip
public void EnumAttachedSurfaces(IUnknown args, IEnumSurfacesCallback fn);Enumerates all the surfaces attached to a given surface.
Return Value:
No return value.
Parameter Description args Application-defined structure that is passed to the enumeration member every time it is called. fn Callback interface that contains callback function that will be called for each surface that is attached to this surface.
public void EnumOverlayZOrders(int flags, IUnknown args, IEnumZOrdersCallback fn);Enumerates the overlay surfaces on the specified destination. The overlays can be enumerated in front-to-back or back-to-front order.
Return Value:
No return value.
Parameter Description flags One value of DDENUMOVERLAYZ_ type. args User-defined context that will be passed to the callback function for each overlay surface. fn Callback interface that contains the callback function that will be called for each surface being overlaid on this surface.
public void Flip(ddSurface ddS, int flags);Makes the surface memory associated with the DDSCAPS_BACKBUFFER surface become associated with the front-buffer surface.
Return Value:
No return value.
Parameter Description ddS The ddSurface object that will be flipped to. The default for this parameter is null, in which case Flip cycles through the buffers in the order they are attached to each other. This parameter is used only as an override. flags Can be DDFLIP_WAIT. Remarks:
This method can be called only by a surface that has the DDSCAPS_FLIP and DDSCAPS_FRONTBUFFER values set. The display memory previously associated with the front buffer is associated with the back buffer. If there is more than one back buffer, a ring is formed and the surface memory buffers cycle one step through it every time Flip is called.
The ddS parameter is used in rare cases when the back buffer is not the buffer that should become the front buffer. Typically this parameter is null.
The Flip method will always be synchronized with the vertical blank.
See Also: GetFlipStatus
public void Flush(Rect r, ddSurfaceDesc d, int flags, int hnd, int[] memory);Flushes the contents of a buffer into the surface memory.
Return Value:
No return value.
Parameter Description r A Rect object that identifies the region of surface that receives the changes. d A ddSurfaceDesc object that contains the relevant details about the surface. flags One or more values of DDLOCK_ type. hnd Handle of a system event that is triggered when the surface is ready to be locked. memory Array variable that contains the new contents of the surface memory. See Also: Lock
public ddSurface GetAttachedSurface(int caps);Obtains the attached surface that has the specified capabilities.
Return Value:
Returns the ddSurface object if successful; null otherwise.
Parameter Description caps A value that specifies the hardware capabilities of the surface. Remarks:
Attachments are used to connect multiple ddSurface objects into complex structures, like the ones needed to support 3D page flipping with z-buffers. This method fails if more than one surface is attached that matches the capabilities requested. In this case, the application must use the EnumAttachedSurfaces method to obtain the attached surfaces.
public int GetBltStatus(int flags);Obtains the blitter status.
Return Value:
Returns DD_OK if a blitter is present, DDERR_WASSTILLDRAWING if the blitter is busy.
Parameter Description flags One value of DDGBS_ type.
public int GetCaps();Retrieves the capabilities of the surface. These capabilities are not necessarily related to the capabilities of the display device.
Return Value:
Returns the hardware capabilities of the surface.
public ddClipper GetClipper();Retrieves the ddClipper object associated with this surface.
Return Value:
Returns the ddClipper object if successful; null otherwise.
See Also: SetClipper
public void GetColorKey(int flags, ddColorKey val);Retrieves the color key value for the ddSurface object.
Return Value:
No return value.
Parameter Description flags One value of DDCKEY_ type, specifying which color key to retrieve information for. val The ddColorKey object that receives the current values for the specified color key of the ddSurface object. See Also: SetColorKey
public int GetDC();Creates a GDI-compatible handle of a device context for the surface.
Return Value:
Returns handle of a device context.
Remarks:
This method uses an internal version of the Lock method to lock the surface. The surface remains locked until the ReleaseDC method is called.
public IUnknown GetDDInterface();Retrieves an interface to the DirectDraw object that was used to create the surface.
Return Value:
Returns the IUnknown object if successful; null otherwise.
public int GetFlipStatus(int flags);Indicates whether the surface has finished its flipping process.
Return Value:
Returns DD_OK if successful, or DDERR_WASSTILLDRAWING if the surfaces has not finished its flipping process.
Parameter Description flags One value of DDGFS_ type. See Also: Flip
public int GetOverlayPositionX();Given a visible, active overlay surface (DDSCAPS_OVERLAY flag set), this method returns the x-display coordinate of the surface.
Return Value:
Returns the x-coordinate.
See Also: GetOverlayPositionY, SetOverlayPosition, UpdateOverlay
public int GetOverlayPositionY();Given a visible, active overlay surface (DDSCAPS_OVERLAY flag set), this method returns the y-display coordinate of the surface.
Return Value:
Returns the y-coordinate.
See Also: GetOverlayPositionX, SetOverlayPosition, UpdateOverlay
public ddPalette GetPalette();Retrieves the ddPalette structure associated with this surface.
Return Value:
Returns the ddPalette object if successful; null otherwise. This is null if no ddPalette object is associated with this surface. If the surface is the primary surface, or a back buffer to the primary surface, and the primary surface is in 8-bpp mode, this method returns the system palette.
See Also: SetPalette
public void GetPixelFormat(ddPixelFormat pf);Retrieves the color and pixel format of the surface.
Return Value:
No return value.
Parameter Description pf A ddPixelFormat object that receives a detailed description of the current pixel and color space format of the surface.
public void GetSurfaceDesc(ddSurfaceDesc surface);Retrieves a description of the surface in its current condition.
Return Value:
No return value.
Parameter Description surface A ddSurfaceDesc object that receives the current description of this surface.
public void Initialize(dDraw dd, ddSurfaceDesc surface);Initializes a ddSurface object.
Return Value:
No return value.
Parameter Description dd The dDraw object. surface A ddSurfaceDesc object that contains the relevant details about the surface.
public int IsLost();Determines if the surface memory associated with a ddSurface object has been freed.
Return Value:
Returns DD_OK if the memory has not been freed.
Remarks:
You can use this method to reallocate surface memory. When a ddSurface object loses its surface memory, most methods perform no function.
Surfaces can lose their memory when the mode of the display card is changed, or when an application receives exclusive access to the display card and frees all of the surface memory currently allocated on the display card.
See Also: Restore
public void Lock(Rect r, ddSurfaceDesc d, int flags, int hnd, int[] memory);Obtains the contents of the surface memory.
Return Value:
No return value.
Parameter Description r A Rect object that identifies the region of surface that is being locked. d A ddSurfaceDesc object that receives the relevant details about the surface. flags One or more values of DDLOCK_ type. hnd Handle of a system event that is triggered when the surface is ready to be locked. memory Array variable that receives the contents of the surface memory. Remarks:
The contents of the surface memory remain valid until the corresponding the Unlock method is called. Applications that change the contents must flush the changes back into system memory by using the Flush method.
Your application cannot blit from a region of a surface that is locked.
Typically, Lock returns immediately when a lock cannot be obtained because a blit is in progress. You can use the DDLOCK_WAIT flag if you want the method to continue trying to obtain a lock.
public void PageLock(int flags);Prevents a system-memory surface from being paged out while a blit using DMA transfers to or from system memory is in progress.
Return Value:
No return value.
Parameter Description flags Reserved; must be 0. Remarks:
The performance of the operating system could be negatively affected if too much memory is locked.
A lock count is maintained for each surface and is incremented each time PageLock is called for that surface. The count is decremented when PageUnlock is called. When the count reaches 0, the memory is unlocked and can then be paged by the operating system.
This method works only on system-memory surfaces; it will not page lock a display-memory surface or an emulated primary surface. If an application calls this method on a display memory surface, the method will do nothing except return DD_OK.
See Also: PageUnlock
public void PageUnlock(int flags);Unlocks a system-memory surface, allowing it to be paged out.
Return Value:
No return value.
Parameter Description flags Reserved; must be 0. Remarks:
A lock count is maintained for each surface and is incremented each time PageLock is called for that surface. The count is decremented when PageUnlock is called. When the count reaches 0, the memory is unlocked and can then be paged by the operating system.
This method works only on system-memory surfaces; it will not page unlock a display-memory surface or an emulated primary surface. If an application calls this method on a display-memory surface, this method will do nothing except return DD_OK.
See Also: PageLock
public void ReleaseDC(int hdc);Releases the handle of a device context previously obtained with the GetDC method.
Return Value:
No return value.
Parameter Description hDC The handle of a device context previously obtained by GetDC. Remarks:
This method also unlocks the surface previously locked when the GetDC method was called.
See Also: GetDC
public int Restore();Restores a surface that has been lost. This occurs when the surface memory associated with the ddSurface object has been freed.
Return Value:
Returns DD_OK is successful.
Remarks:
Surfaces can be lost because the mode of the display card was changed or because an application received exclusive access to the display card and freed all of the surface memory currently allocated on the card. When a ddSurface object loses its surface memory, many methods will return DDERR_SURFACELOST and perform no other function. The Restore method will reallocate surface memory and reattach it to the ddSurface object.
A single call to this method will restore a ddSurface object's associated implicit surfaces (back buffers, and so on). An attempt to restore an implicitly created surface will result in an error. Restore will not work across explicit attachments created by using the AddAttachedSurface method — each of these surfaces must be restored individually.
See Also: IsLost, AddAttachedSurface
public void SetClipper(ddClipper val);Attaches a ddClipper object to a ddSurface object.
Return Value:
No return value.
Parameter Description val The ddClipper object that will be attached to the ddSurface object. If this parameter is null, the current ddClipper object will be detached. Remarks:
This method is primarily used by surfaces that are being overlaid on or blitted to the primary surface. However, it can be used on any surface. After a ddClipper object has been attached and a clip list is associated with it, the ddClipper object will be used for the Blt, BltBatch, and UpdateOverlay operations involving the parent ddSurface object. This method can also detach a ddSurface object's current ddClipper object.
If this method is called several times consecutively on the same surface for the same ddClipper object, the reference count for the object is incremented only once. Subsequent calls do not affect the object's reference count.
See Also: GetClipper
public void SetColorKey(int flags, ddColorKey val);Sets the color key value for the ddSurface object if the hardware supports color keys on a per surface basis.
Return Value:
No return value.
Parameter Description flags One value of DDCKEY_ type, specifying which color key to set. val A ddColorKey object that contains the new color key values for the ddSurface object. See Also: GetColorKey
public void SetOverlayPosition(int x, int y);Changes the display coordinates of an overlay surface.
Return Value:
No return value.
Parameter Description x and y New x- and y-display coordinates. See Also: GetOverlayPositionX, GetOverlayPositionY, UpdateOverlay
public void SetPalette(ddPalette ddp);Attaches the specified ddPalette object to a surface. The surface uses this palette for all subsequent operations. The palette change takes place immediately, without regard to refresh timing.
Return Value:
No return value.
Parameter Description ddp The ddPalette object that this surface should use for future operations. Remarks:
If this method is called several times consecutively on the same surface for the same palette, the reference count for the palette is incremented only once. Subsequent calls do not affect the palette's reference count.
See Also: GetPalette, CreatePalette
public void Unlock(ddSurfaceDesc data);Notifies DirectDraw that the direct surface manipulations are complete.
Return Value:
No return value.
Parameter Description data The ddSurfaceDesc object returned by the Lock method. See Also: Lock
public void UpdateOverlay(Rect r, ddSurface ddS, Rect d, int flags);Repositions or modifies the visual attributes of an overlay surface. These surfaces must have the DDSCAPS_OVERLAY value set.
Return Value:
No return value.
Parameter Description r A Rect object that defines the x, y, width, and height of the region on the source surface being used as the overlay. ddS The ddSurface that is being overlaid. d A Rect object that defines the x, y, width, and height of the region on the destination surface that the overlay should be moved to. flags One or more values of DDOVER_ type.
public void UpdateOverlayDisplay(int flags);Repaints the rectangles in the dirty rectangle list of all active overlays. This clears the dirty rectangle list. This method is for software emulation only—it does nothing if the hardware supports overlays.
Return Value:
No return value.
Parameter Description flags Type of update to perform. Can be DDOVER_REFRESHDIRTYRECTS or DDOVER_REFRESHALL. See Also: AddOverlayDirtyRect
public void UpdateOverlayZOrder(int flags, ddSurface ddS);Sets the z-order of an overlay.
Return Value:
No return value.
Parameter Description flags One value of DDOVERZ_ type. ddS The ddSurface object to be used as a relative position in the overlay chain. This parameter is needed only for DDOVERZ_INSERTINBACKOF and DDOVERZ_INSERTINFRONTOF. See Also: EnumOverlayZOrders
public void CopyBitmap(dBitmap val, int cx, int cy, int dx, int dy);Copies a bitmap.
Return Value:
No return value.
Parameter Description val The dBitmap object cx and cy The x- and y-coordinates of the upper left corner of the bitmap. dx and dy The x- and y-coordinates of the lower right corner of the bitmap.
