public abstract class GraphicsDevice extends Object
GraphicsDevice
class describes the graphics devices
that might be available in a particular graphics environment. These
include screen and printer devices. Note that there can be many screens
and many printers in an instance of GraphicsEnvironment
. Each
graphics device has one or more GraphicsConfiguration
objects
associated with it. These objects specify the different configurations
in which the GraphicsDevice
can be used.
In a multi-screen environment, the GraphicsConfiguration
objects can be used to render components on multiple screens. The
following code sample demonstrates how to create a JFrame
object for each GraphicsConfiguration
on each screen
device in the GraphicsEnvironment
:
GraphicsEnvironment ge = GraphicsEnvironment.
getLocalGraphicsEnvironment();
GraphicsDevice[] gs = ge.getScreenDevices();
for (int j = 0; j < gs.length; j++) {
GraphicsDevice gd = gs[j];
GraphicsConfiguration[] gc =
gd.getConfigurations();
for (int i=0; i < gc.length; i++) {
JFrame f = new
JFrame(gs[j].getDefaultConfiguration());
Canvas c = new Canvas(gc[i]);
Rectangle gcBounds = gc[i].getBounds();
int xoffs = gcBounds.x;
int yoffs = gcBounds.y;
f.getContentPane().add(c);
f.setLocation((i*50)+xoffs, (i*60)+yoffs);
f.show();
}
}
For more information on full-screen exclusive mode API, see the Full-Screen Exclusive Mode API Tutorial.
- See Also:
GraphicsEnvironment
,GraphicsConfiguration
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
GraphicsDevice.WindowTranslucency
Kinds of translucency supported by the underlying system. -
Field Summary
Fields Modifier and Type Field Description static int
TYPE_IMAGE_BUFFER
Device is an image buffer.static int
TYPE_PRINTER
Device is a printer.static int
TYPE_RASTER_SCREEN
Device is a raster screen. -
Constructor Summary
Constructors Modifier Constructor Description protected
GraphicsDevice()
This is an abstract class that cannot be instantiated directly. -
Method Summary
Modifier and Type Method Description int
getAvailableAcceleratedMemory()
This method returns the number of bytes available in accelerated memory on this device.GraphicsConfiguration
getBestConfiguration(GraphicsConfigTemplate gct)
Returns the "best" configuration possible that passes the criteria defined in theGraphicsConfigTemplate
.abstract GraphicsConfiguration[]
getConfigurations()
Returns all of theGraphicsConfiguration
objects associated with thisGraphicsDevice
.abstract GraphicsConfiguration
getDefaultConfiguration()
Returns the defaultGraphicsConfiguration
associated with thisGraphicsDevice
.DisplayMode
getDisplayMode()
Returns the current display mode of thisGraphicsDevice
.DisplayMode[]
getDisplayModes()
Returns all display modes available for thisGraphicsDevice
.Window
getFullScreenWindow()
Returns theWindow
object representing the full-screen window if the device is in full-screen mode.abstract String
getIDstring()
Returns the identification string associated with thisGraphicsDevice
.abstract int
getType()
Returns the type of thisGraphicsDevice
.boolean
isDisplayChangeSupported()
Returnstrue
if thisGraphicsDevice
supports low-level display changes.boolean
isFullScreenSupported()
Returnstrue
if thisGraphicsDevice
supports full-screen exclusive mode.boolean
isWindowTranslucencySupported(GraphicsDevice.WindowTranslucency translucencyKind)
Returns whether the given level of translucency is supported by this graphics device.void
setDisplayMode(DisplayMode dm)
Sets the display mode of this graphics device.void
setFullScreenWindow(Window w)
Enter full-screen mode, or return to windowed mode.
-
Field Details
-
TYPE_RASTER_SCREEN
public static final int TYPE_RASTER_SCREENDevice is a raster screen.- See Also:
- Constant Field Values
-
TYPE_PRINTER
public static final int TYPE_PRINTERDevice is a printer.- See Also:
- Constant Field Values
-
TYPE_IMAGE_BUFFER
public static final int TYPE_IMAGE_BUFFERDevice is an image buffer. This buffer can reside in device or system memory but it is not physically viewable by the user.- See Also:
- Constant Field Values
-
-
Constructor Details
-
GraphicsDevice
protected GraphicsDevice()This is an abstract class that cannot be instantiated directly. Instances must be obtained from a suitable factory or query method.
-
-
Method Details
-
getType
public abstract int getType()Returns the type of thisGraphicsDevice
.- Returns:
- the type of this
GraphicsDevice
, which can either be TYPE_RASTER_SCREEN, TYPE_PRINTER or TYPE_IMAGE_BUFFER. - See Also:
TYPE_RASTER_SCREEN
,TYPE_PRINTER
,TYPE_IMAGE_BUFFER
-
getIDstring
Returns the identification string associated with thisGraphicsDevice
.A particular program might use more than one
GraphicsDevice
in aGraphicsEnvironment
. This method returns aString
identifying a particularGraphicsDevice
in the localGraphicsEnvironment
. Although there is no public method to set thisString
, a programmer can use theString
for debugging purposes. Vendors of the Java Runtime Environment can format the return value of theString
. To determine how to interpret the value of theString
, contact the vendor of your Java Runtime. To find out who the vendor is, from your program, call thegetProperty
method of the System class with "java.vendor".- Returns:
- a
String
that is the identification of thisGraphicsDevice
.
-
getConfigurations
Returns all of theGraphicsConfiguration
objects associated with thisGraphicsDevice
.- Returns:
- an array of
GraphicsConfiguration
objects that are associated with thisGraphicsDevice
.
-
getDefaultConfiguration
Returns the defaultGraphicsConfiguration
associated with thisGraphicsDevice
.- Returns:
- the default
GraphicsConfiguration
of thisGraphicsDevice
.
-
getBestConfiguration
Returns the "best" configuration possible that passes the criteria defined in theGraphicsConfigTemplate
.- Parameters:
gct
- theGraphicsConfigTemplate
object used to obtain a validGraphicsConfiguration
- Returns:
- a
GraphicsConfiguration
that passes the criteria defined in the specifiedGraphicsConfigTemplate
. - See Also:
GraphicsConfigTemplate
-
isFullScreenSupported
public boolean isFullScreenSupported()Returnstrue
if thisGraphicsDevice
supports full-screen exclusive mode. If a SecurityManager is installed, itscheckPermission
method will be called withAWTPermission("fullScreenExclusive")
.isFullScreenSupported
returns true only if that permission is granted.- Returns:
- whether full-screen exclusive mode is available for this graphics device
- Since:
- 1.4
- See Also:
AWTPermission
-
setFullScreenWindow
Enter full-screen mode, or return to windowed mode. The entered full-screen mode may be either exclusive or simulated. Exclusive mode is only available ifisFullScreenSupported
returnstrue
.Exclusive mode implies:
- Windows cannot overlap the full-screen window. All other application windows will always appear beneath the full-screen window in the Z-order.
- There can be only one full-screen window on a device at any time, so calling this method while there is an existing full-screen Window will cause the existing full-screen window to return to windowed mode.
- Input method windows are disabled. It is advisable to call
Component.enableInputMethods(false)
to make a component a non-client of the input method framework.
The simulated full-screen mode places and resizes the window to the maximum possible visible area of the screen. However, the native windowing system may modify the requested geometry-related data, so that the
Window
object is placed and sized in a way that corresponds closely to the desktop settings.When entering full-screen mode, if the window to be used as a full-screen window is not visible, this method will make it visible. It will remain visible when returning to windowed mode.
When entering full-screen mode, all the translucency effects are reset for the window. Its shape is set to
null
, the opacity value is set to 1.0f, and the background color alpha is set to 255 (completely opaque). These values are not restored when returning to windowed mode.It is unspecified and platform-dependent how decorated windows operate in full-screen mode. For this reason, it is recommended to turn off the decorations in a
Frame
orDialog
object by using thesetUndecorated
method.When returning to windowed mode from an exclusive full-screen window, any display changes made by calling
setDisplayMode
are automatically restored to their original state.- Parameters:
w
- a window to use as the full-screen window;null
if returning to windowed mode. Some platforms expect the fullscreen window to be a top-level component (i.e., aFrame
); therefore it is preferable to use aFrame
here rather than aWindow
.- Since:
- 1.4
- See Also:
isFullScreenSupported()
,getFullScreenWindow()
,setDisplayMode(java.awt.DisplayMode)
,Component.enableInputMethods(boolean)
,Component.setVisible(boolean)
,Frame.setUndecorated(boolean)
,Dialog.setUndecorated(boolean)
-
getFullScreenWindow
Returns theWindow
object representing the full-screen window if the device is in full-screen mode.- Returns:
- the full-screen window, or
null
if the device is not in full-screen mode. - Since:
- 1.4
- See Also:
setFullScreenWindow(Window)
-
isDisplayChangeSupported
public boolean isDisplayChangeSupported()Returnstrue
if thisGraphicsDevice
supports low-level display changes. On some platforms low-level display changes may only be allowed in full-screen exclusive mode (i.e., ifisFullScreenSupported()
returnstrue
and the application has already entered full-screen mode usingsetFullScreenWindow(java.awt.Window)
).- Returns:
- whether low-level display changes are supported for this graphics device.
- Since:
- 1.4
- See Also:
isFullScreenSupported()
,setDisplayMode(java.awt.DisplayMode)
,setFullScreenWindow(java.awt.Window)
-
setDisplayMode
Sets the display mode of this graphics device. This is only allowed ifisDisplayChangeSupported()
returnstrue
and may require first entering full-screen exclusive mode usingsetFullScreenWindow(java.awt.Window)
providing that full-screen exclusive mode is supported (i.e.,isFullScreenSupported()
returnstrue
).The display mode must be one of the display modes returned by
getDisplayModes()
, with one exception: passing a display mode withDisplayMode.REFRESH_RATE_UNKNOWN
refresh rate will result in selecting a display mode from the list of available display modes with matching width, height and bit depth. However, passing a display mode withDisplayMode.BIT_DEPTH_MULTI
for bit depth is only allowed if such mode exists in the list returned bygetDisplayModes()
.Example code:
Frame frame; DisplayMode newDisplayMode; GraphicsDevice gd; // create a Frame, select desired DisplayMode from the list of modes // returned by gd.getDisplayModes() ... if (gd.isFullScreenSupported()) { gd.setFullScreenWindow(frame); } else { // proceed in non-full-screen mode frame.setSize(...); frame.setLocation(...); frame.setVisible(true); } if (gd.isDisplayChangeSupported()) { gd.setDisplayMode(newDisplayMode); }
- Parameters:
dm
- The new display mode of this graphics device.- Throws:
IllegalArgumentException
- if theDisplayMode
supplied isnull
, or is not available in the array returned bygetDisplayModes
UnsupportedOperationException
- ifisDisplayChangeSupported
returnsfalse
- Since:
- 1.4
- See Also:
getDisplayMode()
,getDisplayModes()
,isDisplayChangeSupported()
-
getDisplayMode
Returns the current display mode of thisGraphicsDevice
. The returned display mode is allowed to have a refresh rateDisplayMode.REFRESH_RATE_UNKNOWN
if it is indeterminate. Likewise, the returned display mode is allowed to have a bit depthDisplayMode.BIT_DEPTH_MULTI
if it is indeterminate or if multiple bit depths are supported.- Returns:
- the current display mode of this graphics device.
- Since:
- 1.4
- See Also:
setDisplayMode(DisplayMode)
-
getDisplayModes
Returns all display modes available for thisGraphicsDevice
. The returned display modes are allowed to have a refresh rateDisplayMode.REFRESH_RATE_UNKNOWN
if it is indeterminate. Likewise, the returned display modes are allowed to have a bit depthDisplayMode.BIT_DEPTH_MULTI
if it is indeterminate or if multiple bit depths are supported.- Returns:
- all of the display modes available for this graphics device.
- Since:
- 1.4
-
getAvailableAcceleratedMemory
public int getAvailableAcceleratedMemory()This method returns the number of bytes available in accelerated memory on this device. Some images are created or cached in accelerated memory on a first-come, first-served basis. On some operating systems, this memory is a finite resource. Calling this method and scheduling the creation and flushing of images carefully may enable applications to make the most efficient use of that finite resource.
Note that the number returned is a snapshot of how much memory is available; some images may still have problems being allocated into that memory. For example, depending on operating system, driver, memory configuration, and thread situations, the full extent of the size reported may not be available for a given image. There are further inquiry methods on theImageCapabilities
object associated with a VolatileImage that can be used to determine whether a particular VolatileImage has been created in accelerated memory.- Returns:
- number of bytes available in accelerated memory. A negative return value indicates that the amount of accelerated memory on this GraphicsDevice is indeterminate.
- Since:
- 1.4
- See Also:
Image.flush()
,ImageCapabilities.isAccelerated()
-
isWindowTranslucencySupported
Returns whether the given level of translucency is supported by this graphics device.- Parameters:
translucencyKind
- a kind of translucency support- Returns:
- whether the given translucency kind is supported
- Since:
- 1.7
-