Class DirectDrawSurface
public class DirectDrawSurface implements IDirectDrawSurface
{
// Methods
public void addAttachedSurface(DirectDrawSurface ddS);
public void addOverlayDirtyRect(Rect r);
public int blt(Rect dest, DirectDrawSurface ddS, Rect src,
int flags);
public int bltColorFill(Rect dest, int fillValue);
public int bltFast(int dx, int dy, DirectDrawSurface ddS,
Rect src, int trans);
public int bltFx(Rect dest, DirectDrawSurface ddS, Rect src,
int flags, DDBltFx bltFx);
public void copyBitmap(DirectDrawBitmap val, int cx, int cy,
int dx, int dy);
public Direct3dDevice create3DDevice(_Guid g);
public void deleteAttachedSurface(int flags,
DirectDrawSurface ddS);
public void enumAttachedSurfaces(IUnknown args,
IEnumSurfacesCallback fn);
public void enumOverlayZOrders(int flags, IUnknown args,
IEnumZOrdersCallback fn);
public void flip(DirectDrawSurface ddS, int flags);
public DirectDrawSurface getAttachedSurface(int caps);
public int getBltStatus(int flags);
public int getCaps();
public DirectDrawClipper getClipper();
public void getColorKey(int flags, DDColorKey val);
public int getDC();
public IUnknown getDDInterface();
public int getFlipStatus(int flags);
public int getOverlayPositionX();
public int getOverlayPositionY();
public DirectDrawPalette getPalette();
public void getPixelFormat(DDPixelFormat pf);
public void getSurfaceDesc(DDSurfaceDesc surface);
public int isLost();
public void lock(Rect r, DDSurfaceDesc d, int flags, int hnd,
byte[] memory);
public void releaseDC(int hdc);
public int restore();
public void setClipper(DirectDrawClipper val);
public void setColorKey(int flags, DDColorKey val);
public void setOverlayPosition(int x, int y);
public void setPalette(DirectDrawPalette ddp);
public void unlock(Rect r, DDSurfaceDesc d, byte[] memory);
public void updateOverlay(Rect r, DirectDrawSurface ddS, Rect d,
int flags);
public void updateOverlayDisplay(int flags);
public void updateOverlayZOrder(int flags, DirectDrawSurface ddS);
}
Applications use the methods of the DirectDrawSurface class to create Microsoft® DirectDraw® surface objects and work with system-level variables.
Note This class does not provide an initialize method. Use the DirectDraw.createSurface method to create and initialize DirectDrawSurface objects.
public void addAttachedSurface(DirectDrawSurface ddS);
Attaches a surface to another surface.
Return Value:
No return value.
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, DirectDrawSurface ddS, Rect src, int flags);
Performs a bit block transfer.
Return Value:
Returns S_OK or 0 if the blit was set successfully; otherwise, returns an HRESULT error code. Use the DDBLT_WAIT flag to modify the return behavior as previously discussed.
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 int bltColorFill(Rect dest, int fillValue);
Fills the given rectangle on the surface with the given fill value.
Return Value:
Returns S_OK or 0 if the operation is successful; otherwise, returns an error code.
Parameter | Description |
dest
| A Rect object that defines the upper-left and lower-right points of the rectangle on the destination surface to be filled.
|
fillvalue
| The fill value to fill the rectangle with.
|
public int bltFast(int dx, int dy, DirectDrawSurface 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 S_OK or 0 if the operation is successful; otherwise, returns an error code.
Parameter | Description |
dx
| |
dy
| The x and y coordinates to blit to on the destination surface.
|
ddS
| The DirectDrawSurface 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 int bltFx(Rect dest, DirectDrawSurface ddS, Rect src, int flags,
DDBltFx bltFx);
This method is capable of synchronous or asynchronous blits, in one of the following formats:
- display memory to display memory
- display memory to system memory
- system memory to display memory
- 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.
Return Value:
Returns S_OK or 0 if the operation is successful; otherwise, returns an error code.
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 DirectDrawSurface 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
| This parameter is currently not used and must be set to 0.
|
bltfx
| The DDBltFx object that defines the parameters for the blit operations.
|
public void copyBitmap(DirectDrawBitmap val, int cx, int cy, int dx,
int dy);
Copies a bitmap.
Return Value:
No return value.
Parameter | Description |
val
| The DirectDrawBitmap object
|
cx
| The bitmap's upper-left x coordinate.
|
cy
| The bitmap's upper-left y coordinate.
|
dx
| The bitmap's lower-right x coordinate.
|
dy
| The bitmap's lower-right y coordinate.
|
public Direct3dDevice create3DDevice(_Guid g);
Creates a device from the surface if you want a rendering surface. This method emulates the IUnknown interface's HRESULT QueryInterface(REFIID riid, LPVOID* obp); COM method inherited by DirectX3 COM interfaces.
Return Value:
Returns a Direct3dDevice object that acts as a rendering surface.
Parameter | Description |
g
| A globally unique identifier retrieved with the enumDevices method.
|
public void deleteAttachedSurface(int flags, DirectDrawSurface 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 DirectDrawSurface 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(DirectDrawSurface 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 DirectDrawSurface 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 DirectDrawSurface getAttachedSurface(int caps);
Obtains the attached surface that has the specified capabilities.
Return Value:
Returns the DirectDrawSurface object if successful; otherwise, returns null.
Parameter | Description |
caps
| A value that specifies the hardware capabilities of the surface.
|
Remarks:
Attachments are used to connect multiple DirectDrawSurface 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 DirectDrawClipper getClipper();
Retrieves the DirectDrawClipper object associated with this surface.
Return Value:
Returns the DirectDrawClipper object if successful; null otherwise.
See Also: setClipper
public void getColorKey(int flags, DDColorKey val);
Retrieves the color key value for the DirectDrawSurface 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 DirectDrawSurface object.
|
See Also: setColorKey
public int getDC();
Creates a Graphical Device Interface-compatible handle of a device context for the surface.
Return Value:
Returns the handle of a device context.
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 DirectDrawPalette getPalette();
Retrieves the DirectDrawPalette structure associated with this surface.
Return Value:
Returns the DirectDrawPalette object if successful; null otherwise. This is null if no DirectDrawPalette 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 int isLost();
Determines if the surface memory associated with a DirectDrawSurface 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 DirectDrawSurface 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,
byte[] 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 (use the unlock for this as well).
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.
See Also: unlock
public void releaseDC(int hdc);
Releases the handle of a device context previously obtained by using the getDC method.
Return Value:
No return value.
Parameter | Description |
hdc
| The handle of a device context.
|
public int restore();
Restores a surface that has been lost. This occurs when the surface memory associated with the DirectDrawSurface 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 DirectDrawSurface 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 DirectDrawSurface object.
A single call to this method will restore a DirectDrawSurface 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 methodeach of these surfaces must be restored individually.
See Also: isLost, addAttachedSurface
public void setClipper(DirectDrawClipper val);
Attaches a DirectDrawClipper object to a DirectDrawSurface object.
Return Value:
No return value.
Parameter | Description |
val
| The DirectDrawClipper object that will be attached to the DirectDrawSurface object. If this parameter is null, the current DirectDrawClipper 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 DirectDrawClipper object has been attached and a clip list is associated with it, the DirectDrawClipper object will be used for the blt and updateOverlay operations involving the parent DirectDrawSurface object. This method can also detach a DirectDrawSurface object's current DirectDrawClipper object.
If this method is called several times consecutively on the same surface for the same DirectDrawClipper 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 DirectDrawSurface 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 DirectDrawSurface 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
| New x-display coordinate.
|
y
| New y-display coordinate.
|
See Also: getOverlayPositionX, getOverlayPositionY, updateOverlay
public void setPalette(DirectDrawPalette ddp);
Attaches the specified DirectDrawPalette 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 DirectDrawPalette 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 effect the palette's reference count.
See Also: getPalette, com.ms.directX.DirectDraw.createPalette
public void unlock(Rect r, DDSurfaceDesc d, byte[] memory);
Notifies DirectDraw that the direct surface manipulations are complete and copies the contents of the memory buffer into the surface.
Return Value:
No return value.
Parameter | Description |
r
| A Rect object that identifies the region of surface that receives the changes.
|
d
| The DDSurfaceDesc object returned by the lock method.
|
memory
| Array variable that contains the new contents of the surface memory.
|
See Also: lock
public void updateOverlay(Rect r, DirectDrawSurface 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 DirectDrawSurface 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 onlyit does nothing if the hardware supports overlays.
Return Value:
No return value.
See Also: addOverlayDirtyRect
public void updateOverlayZOrder(int flags, DirectDrawSurface ddS);
Sets the z-order of an overlay.
Return Value:
No return value.
See Also: enumOverlayZOrders