public abstract class

SurfaceData

extends Object
implements Transparency DisposerTarget StateTrackable
java.lang.Object
   ↳ sun.java2d.SurfaceData
Known Direct Subclasses

Class Overview

This class provides various pieces of information relevant to a particular drawing surface. The information obtained from this object describes the pixels of a particular instance of a drawing surface and can only be shared among the various graphics objects that target the same BufferedImage or the same screen Component.

Each SurfaceData object holds a StateTrackableDelegate object which tracks both changes to the content of the pixels of this surface and changes to the overall state of the pixels - such as becoming invalid or losing the surface. The delegate is marked "dirty" whenever the setSurfaceLost() or invalidate() methods are called and should also be marked "dirty" by the rendering pipelines whenever they modify the pixels of this SurfaceData.

If you get a StateTracker from a SurfaceData and it reports that it is still "current", then you can trust that the pixels have not changed and that the SurfaceData is still valid and has not lost its underlying storage (surfaceLost) since you retrieved the tracker.

Summary

[Expand]
Inherited Constants
From interface java.awt.Transparency
Fields
protected static final AAShapePipe AAClipColorShape
protected static final PixelToShapeConverter AAClipColorViaShape
protected static final AAShapePipe AAClipCompShape
protected static final PixelToShapeConverter AAClipCompViaShape
protected static final AAShapePipe AAClipPaintShape
protected static final PixelToShapeConverter AAClipPaintViaShape
protected static final AAShapePipe AAColorShape
protected static final PixelToShapeConverter AAColorViaShape
protected static final AAShapePipe AACompShape
protected static final PixelToShapeConverter AACompViaShape
protected static final AAShapePipe AAPaintShape
protected static final PixelToShapeConverter AAPaintViaShape
public static final TextPipe aaTextRenderer
protected static final CompositePipe clipColorPipe
protected static final TextPipe clipColorText
protected static final CompositePipe clipCompPipe
protected static final TextPipe clipCompText
protected static final CompositePipe clipPaintPipe
protected static final TextPipe clipPaintText
protected static final CompositePipe colorPipe
protected static final LoopPipe colorPrimitives
protected static final TextPipe colorText
protected static final PixelToShapeConverter colorViaShape
protected static final CompositePipe compPipe
protected static final SpanShapeRenderer compShape
protected static final TextPipe compText
protected static final PixelToShapeConverter compViaShape
protected static final DrawImagePipe imagepipe
public static final TextPipe lcdTextRenderer
public static final TextPipe outlineTextRenderer
protected static final CompositePipe paintPipe
protected static final SpanShapeRenderer paintShape
protected static final TextPipe paintText
protected static final PixelToShapeConverter paintViaShape
public static final TextPipe solidTextRenderer
Protected Constructors
SurfaceData(SurfaceType surfaceType, ColorModel cm)
SurfaceData(StateTrackable.State state, SurfaceType surfaceType, ColorModel cm)
SurfaceData(StateTrackableDelegate trackable, SurfaceType surfaceType, ColorModel cm)
SurfaceData(StateTrackable.State state)
Public Methods
boolean canRenderLCDText(SunGraphics2D sg2d)
boolean copyArea(SunGraphics2D sg2d, int x, int y, int w, int h, int dx, int dy)
Performs a copyarea within this surface.
void flush()
Synchronously releases resources associated with this surface.
abstract Rectangle getBounds()
Returns the bounds of the destination surface.
final ColorModel getColorModel()
Return the ColorModel for the destination surface.
abstract Object getDestination()
Returns destination associated with this SurfaceData.
abstract GraphicsConfiguration getDeviceConfiguration()
Return the GraphicsConfiguration object that describes this destination surface.
Object getDisposerReferent()
Returns an object which will be used as the referent in the ReferenceQueue
long getNativeOps()
static SurfaceData getPrimarySurfaceData(Image img)
Extracts the SurfaceManager from the given Image, and then returns the SurfaceData object that would best be suited as the destination surface in some rendering operation.
abstract Raster getRaster(int x, int y, int w, int h)
Return a readable Raster which contains the pixels for the specified rectangular region of the destination surface.
RenderLoops getRenderLoops(SunGraphics2D sg2d)
Return a RenderLoops object containing all of the basic GraphicsPrimitive objects for rendering to the destination surface with the current attributes of the given SunGraphics2D.
abstract SurfaceData getReplacement()
Certain changes in the configuration of a surface require the invalidation of existing associated SurfaceData objects and the creation of brand new ones.
SurfaceData getSourceSurfaceData(Image img, int txtype, CompositeType comp, Color bgColor)
This method is called on a destination SurfaceData to choose the best SurfaceData from a source Image for an imaging operation, with help from its SurfaceManager.
StateTrackable.State getState()
Returns the general state of the complex data held by this object.
StateTracker getStateTracker()
Returns an object which can track future changes to the complex data stored in this object.
final SurfaceType getSurfaceType()
Return the SurfaceType object that describes the destination surface.
int getTransparency()
Returns the type of this Transparency.
void invalidate()
Sets this SurfaceData object to the invalid state.
static boolean isNull(SurfaceData sd)
For our purposes null and NullSurfaceData are the same as they represent a disposed surface.
boolean isSurfaceLost()
final boolean isValid()
Returns a boolean indicating whether or not this SurfaceData is valid.
SurfaceDataProxy makeProxyFor(SurfaceData srcData)
This method is called on a destination SurfaceData to choose a proper SurfaceDataProxy subclass for a source SurfaceData to use to control when and with what surface to override a given image operation.
static RenderLoops makeRenderLoops(SurfaceType src, CompositeType comp, SurfaceType dst)
Construct and return a RenderLoops object containing all of the basic GraphicsPrimitive objects for rendering to the destination surface with the given source, destination, and composite types.
final void markDirty()
Marks this surface as dirty.
int pixelFor(int rgb)
Returns the pixel data for the specified Argb value packed into an integer for easy storage and conveyance.
int pixelFor(Color c)
Returns the pixel data for the specified color packed into an integer for easy storage and conveyance.
static SurfaceData restoreContents(Image img)
Restores the contents of the given Image and then returns the new SurfaceData object in use by the Image's SurfaceManager.
int rgbFor(int pixel)
Returns the Argb representation for the specified integer value which is packed in the format of the associated ColorModel.
void setSurfaceLost(boolean lost)
Sets the value of the surfaceLost variable, which indicates whether something has happened to the rendering surface such that it needs to be restored and re-rendered.
boolean useTightBBoxes()
Does the pixel accessibility of the destination surface suggest that rendering algorithms might want to take extra time to calculate a more accurate bounding box for the operation being performed? The typical case when this will be true is when a copy of the pixels has to be made when doing a getRaster.
void validatePipe(SunGraphics2D sg2d)
Protected Methods
void checkCustomComposite()
Performs Security Permissions checks to see if a Custom Composite object should be allowed access to the pixels of this surface.
MaskFill getMaskFill(SunGraphics2D sg2d)
Returns a MaskFill object that can be used on this destination with the source (paint) and composite types determined by the given SunGraphics2D, or null if no such MaskFill object can be located.
static boolean isOpaqueGray(IndexColorModel icm)
Fetches private field IndexColorModel.allgrayopaque which is true when all palette entries in the color model are gray and opaque.
void setBlitProxyKey(Object key)
Subclasses can set a "blit proxy key" which will be used along with the SurfaceManager.getCacheData() mechanism to store acceleration-compatible cached copies of source images.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.awt.Transparency
From interface sun.java2d.DisposerTarget
From interface sun.java2d.StateTrackable

Fields

protected static final AAShapePipe AAClipColorShape

protected static final PixelToShapeConverter AAClipColorViaShape

protected static final AAShapePipe AAClipCompShape

protected static final PixelToShapeConverter AAClipCompViaShape

protected static final AAShapePipe AAClipPaintShape

protected static final PixelToShapeConverter AAClipPaintViaShape

protected static final AAShapePipe AAColorShape

protected static final PixelToShapeConverter AAColorViaShape

protected static final AAShapePipe AACompShape

protected static final PixelToShapeConverter AACompViaShape

protected static final AAShapePipe AAPaintShape

protected static final PixelToShapeConverter AAPaintViaShape

public static final TextPipe aaTextRenderer

protected static final CompositePipe clipColorPipe

protected static final TextPipe clipColorText

protected static final CompositePipe clipCompPipe

protected static final TextPipe clipCompText

protected static final CompositePipe clipPaintPipe

protected static final TextPipe clipPaintText

protected static final CompositePipe colorPipe

protected static final LoopPipe colorPrimitives

protected static final TextPipe colorText

protected static final PixelToShapeConverter colorViaShape

protected static final CompositePipe compPipe

protected static final SpanShapeRenderer compShape

protected static final TextPipe compText

protected static final PixelToShapeConverter compViaShape

protected static final DrawImagePipe imagepipe

public static final TextPipe lcdTextRenderer

public static final TextPipe outlineTextRenderer

protected static final CompositePipe paintPipe

protected static final SpanShapeRenderer paintShape

protected static final TextPipe paintText

protected static final PixelToShapeConverter paintViaShape

public static final TextPipe solidTextRenderer

Protected Constructors

protected SurfaceData (SurfaceType surfaceType, ColorModel cm)

protected SurfaceData (StateTrackable.State state, SurfaceType surfaceType, ColorModel cm)

protected SurfaceData (StateTrackableDelegate trackable, SurfaceType surfaceType, ColorModel cm)

protected SurfaceData (StateTrackable.State state)

Public Methods

public boolean canRenderLCDText (SunGraphics2D sg2d)

public boolean copyArea (SunGraphics2D sg2d, int x, int y, int w, int h, int dx, int dy)

Performs a copyarea within this surface. Returns false if there is no algorithm to perform the copyarea given the current settings of the SunGraphics2D.

public void flush ()

Synchronously releases resources associated with this surface.

public abstract Rectangle getBounds ()

Returns the bounds of the destination surface.

public final ColorModel getColorModel ()

Return the ColorModel for the destination surface.

public abstract Object getDestination ()

Returns destination associated with this SurfaceData. This could be either an Image or a Component; subclasses of SurfaceData are responsible for returning the appropriate object.

public abstract GraphicsConfiguration getDeviceConfiguration ()

Return the GraphicsConfiguration object that describes this destination surface.

public Object getDisposerReferent ()

Returns an object which will be used as the referent in the ReferenceQueue

public long getNativeOps ()

public static SurfaceData getPrimarySurfaceData (Image img)

Extracts the SurfaceManager from the given Image, and then returns the SurfaceData object that would best be suited as the destination surface in some rendering operation.

public abstract Raster getRaster (int x, int y, int w, int h)

Return a readable Raster which contains the pixels for the specified rectangular region of the destination surface. The coordinate origin of the returned Raster is the same as the device space origin of the destination surface. In some cases the returned Raster might also be writeable. In most cases, the returned Raster might contain more pixels than requested.

See Also
  • useTightBBoxes

public RenderLoops getRenderLoops (SunGraphics2D sg2d)

Return a RenderLoops object containing all of the basic GraphicsPrimitive objects for rendering to the destination surface with the current attributes of the given SunGraphics2D.

public abstract SurfaceData getReplacement ()

Certain changes in the configuration of a surface require the invalidation of existing associated SurfaceData objects and the creation of brand new ones. These changes include size, ColorModel, or SurfaceType. Existing Graphics objects which are directed at such surfaces, however, must continue to render to them even after the change occurs underneath the covers. The getReplacement() method is called from SunGraphics2D.revalidateAll() when the associated SurfaceData is found to be invalid so that a Graphics object can continue to render to the surface in its new configuration. Such changes only tend to happen to window based surfaces since most image based surfaces never change size or pixel format. Even VolatileImage objects never change size and they only change their pixel format when manually validated against a new GraphicsConfiguration, at which point old Graphics objects are no longer expected to render to them after the validation step. Thus, only window based surfaces really need to deal with this form of replacement.

public SurfaceData getSourceSurfaceData (Image img, int txtype, CompositeType comp, Color bgColor)

This method is called on a destination SurfaceData to choose the best SurfaceData from a source Image for an imaging operation, with help from its SurfaceManager. The method may determine that the default SurfaceData was really the best choice in the first place, or it may decide to use a cached surface. Some general decisions about whether acceleration is enabled are made by this method, but any decision based on the type of the source image is made in the makeProxyFor method below when it comes up with the appropriate SurfaceDataProxy instance. The parameters describe the type of imaging operation being performed.

If a blitProxyKey was supplied by the subclass then it is used to potentially override the choice of source SurfaceData. The outline of this process is:

  1. Image pipeline asks destSD to find an appropriate srcSD for a given source Image object.
  2. destSD gets the SurfaceManager of the source Image and first retrieves the default SD from it using getPrimarySurfaceData()
  3. destSD uses its "blit proxy key" (if set) to look for some cached data stored in the source SurfaceManager
  4. If the cached data is null then makeProxyFor() is used to create some cached data which is stored back in the source SurfaceManager under the same key for future uses.
  5. The cached data will be a SurfaceDataProxy object.
  6. The SurfaceDataProxy object is then consulted to return a replacement SurfaceData object (typically a cached copy if appropriate, or the original if not).

public StateTrackable.State getState ()

Returns the general state of the complex data held by this object. This return value can be used to determine if it makes strategic sense to try and cache information about the current contents of this object. The StateTracker returned from the getStateTracker() method will further aid in determining when the data has been changed so that the caches can be verified upon future uses.

Returns
  • the current state of trackability of the complex data stored in this object.

public StateTracker getStateTracker ()

Returns an object which can track future changes to the complex data stored in this object. If an external agent caches information about the complex data of this object, it should first get a StateTracker object from this method so that it can check if such information is current upon future uses. Note that a valid StateTracker will always be returned regardless of the return value of getState(), but in some cases the StateTracker may be a trivial implementation which always returns the same value from its isCurrent method.

  • If the current state is IMMUTABLE, this StateTracker and any future StateTracker objects returned from this method will always indicate that the state has not changed.
  • If the current state is UNTRACKABLE, this StateTracker and any future StateTracker objects returned from this method will always indicate that the state has changed.
  • If the current state is DYNAMIC, this StateTracker may always indicate that the current state has changed, but another StateTracker returned from this method in the future when the state has changed to STABLE will correctly track changes.
  • Otherwise the current state is STABLE and this StateTracker will indicate whether or not the data has changed since the time at which it was fetched from the object.

Returns
  • an object implementing the StateTracker interface that tracks whether changes have been made to the complex contents of this object since it was returned.

public final SurfaceType getSurfaceType ()

Return the SurfaceType object that describes the destination surface.

public int getTransparency ()

Returns the type of this Transparency.

Returns
  • the field type of this Transparency, which is either OPAQUE, BITMASK or TRANSLUCENT.

public void invalidate ()

Sets this SurfaceData object to the invalid state. All Graphics objects must get a new SurfaceData object via the refresh method and revalidate their pipelines before continuing.

public static boolean isNull (SurfaceData sd)

For our purposes null and NullSurfaceData are the same as they represent a disposed surface.

public boolean isSurfaceLost ()

public final boolean isValid ()

Returns a boolean indicating whether or not this SurfaceData is valid.

public SurfaceDataProxy makeProxyFor (SurfaceData srcData)

This method is called on a destination SurfaceData to choose a proper SurfaceDataProxy subclass for a source SurfaceData to use to control when and with what surface to override a given image operation. The argument is the default SurfaceData for the source Image.

The type of the return object is chosen based on the acceleration capabilities of this SurfaceData and the type of the given source SurfaceData object.

In some cases the original SurfaceData will always be the best choice to use to blit to this SurfaceData. This can happen if the source image is a hardware surface of the same type as this one and so acceleration will happen without any caching. It may also be the case that the source image can never be accelerated on this SurfaceData - for example because it is translucent and there are no accelerated translucent image ops for this surface.

In those cases there is a special SurfaceDataProxy.UNCACHED instance that represents a NOP for caching purposes - it always returns the original sourceSD object as the replacement copy so no caching is ever performed.

public static RenderLoops makeRenderLoops (SurfaceType src, CompositeType comp, SurfaceType dst)

Construct and return a RenderLoops object containing all of the basic GraphicsPrimitive objects for rendering to the destination surface with the given source, destination, and composite types.

public final void markDirty ()

Marks this surface as dirty.

public int pixelFor (int rgb)

Returns the pixel data for the specified Argb value packed into an integer for easy storage and conveyance.

public int pixelFor (Color c)

Returns the pixel data for the specified color packed into an integer for easy storage and conveyance. This method will use the getRGB() method of the Color object and defer to the pixelFor(int rgb) method if not overridden. For now this is a convenience function, but for cases where the highest quality color conversion is requested, this method should be overridden in those cases so that a more direct conversion of the color to the destination color space can be done using the additional information in the Color object.

public static SurfaceData restoreContents (Image img)

Restores the contents of the given Image and then returns the new SurfaceData object in use by the Image's SurfaceManager.

public int rgbFor (int pixel)

Returns the Argb representation for the specified integer value which is packed in the format of the associated ColorModel.

public void setSurfaceLost (boolean lost)

Sets the value of the surfaceLost variable, which indicates whether something has happened to the rendering surface such that it needs to be restored and re-rendered.

public boolean useTightBBoxes ()

Does the pixel accessibility of the destination surface suggest that rendering algorithms might want to take extra time to calculate a more accurate bounding box for the operation being performed? The typical case when this will be true is when a copy of the pixels has to be made when doing a getRaster. The fewer pixels copied, the faster the operation will go.

See Also
  • getRaster

public void validatePipe (SunGraphics2D sg2d)

Protected Methods

protected void checkCustomComposite ()

Performs Security Permissions checks to see if a Custom Composite object should be allowed access to the pixels of this surface.

protected MaskFill getMaskFill (SunGraphics2D sg2d)

Returns a MaskFill object that can be used on this destination with the source (paint) and composite types determined by the given SunGraphics2D, or null if no such MaskFill object can be located. Subclasses can override this method if they wish to filter other attributes (such as the hardware capabilities of the destination surface) before returning a specific MaskFill object.

protected static boolean isOpaqueGray (IndexColorModel icm)

Fetches private field IndexColorModel.allgrayopaque which is true when all palette entries in the color model are gray and opaque.

protected void setBlitProxyKey (Object key)

Subclasses can set a "blit proxy key" which will be used along with the SurfaceManager.getCacheData() mechanism to store acceleration-compatible cached copies of source images. This key is a "tag" used to identify which cached copies are compatible with this destination SurfaceData. The getSourceSurfaceData() method uses this key to manage cached copies of a source image as described below.

The Object used as this key should be as unique as it needs to be to ensure that multiple acceleratible destinations can each store their cached copies separately under different keys without interfering with each other or getting back the wrong cached copy.

Many acceleratable SurfaceData objects can use their own GraphicsConfiguration as their proxy key as the GC object will typically be unique to a given screen and pixel format, but other rendering destinations may have more or less stringent sharing requirements. For instance, X11 pixmaps can be shared on a given screen by any GraphicsConfiguration that has the same depth and SurfaceType. Multiple such GCs with the same depth and SurfaceType can exist per screen so storing a different cached proxy for each would be a waste. One can imagine platforms where a single cached copy can be created and shared across all screens and pixel formats - such implementations could use a single heavily shared key Object.