Package gumbo.graphic

Provides interfaces, services, and utilities that support application development independent of the implementing graphics technology, dimensionality, and precision.

See:
          Description

Interface Summary
Graphic The base interface for all graphic entities and capabilities that Gumbo uses in a graphic system neutral way.
GraphicFactory A factory interface that creates graphic objects of a common and vital nature.
GraphicPresence A graphic resource with a presence, which the user can sense (sight, sound, touch).
GraphicResource An "abstract" base interface for graphic entities backed by system resources (such as shapes, sounds, pickers, colliders), and which may require disposal of those resources.
 

Class Summary
DefaultGraphicFactory The default graphic factory, which makes no use of the native graphic system.
GlobalGraphicFactory Provides a common point of access for the graphic factory used by the client and system.
GraphicSystem Constants and utilities that provide system specific information, including that of the operating operating system and the native graphic system.
GraphicUtils Constants and utilities that are commonly used by Graphic implementations.
 

Package gumbo.graphic Description

Provides interfaces, services, and utilities that support application development independent of the implementing graphics technology, dimensionality, and precision.

Overview

Technology independence is achieved through the use of common data classes, primarily interfaces, defined in and under this package, which are broad in scope and general purpose in nature.  By relying on interfaces to define Gumbo graphic services and capabilities, Gumbo graphic implementations do require inheritance from Gumbo base classes.

Dimensional independence and simplicity (at the expense of performance, although slight) is achieved by defining the graphic classes for use with all spatial dimensions up to 3D, and by using the double type for all data parameters.  Unused dimension values are simply set to a null operation value (zero for position, one for scale, etc.), and integer arithmetic is handled by rounding.

Background

The graphic spaces defined in the this package are based on those described in the book 3D User Interfaces with Java 3D.  They are used for both 2D and 3D, with 2D implementations severly limiting the available operations that can be performed in the spaces.  Some of the classes were inspired by those in javax.vecmath, AWT, Swing, and various personal libraries developed for ray-tracing and collision detection.

Although some of the classes duplicate the functionality of those in javax.vecmath and the AWT and Swing packages, the classes here are specifically designed for graphics independence and to allow the option of immutability (see below), which helps to minimize the creation of small objects.

Coordinates and Units

The classes in this package have no inherent coordinate system (right-handed, matrix, mouse, etc.) or units (inches, meters, etc.).  For situations requiring a coordinate system, such as the graphic spaces in the package gumbo.graphic.space, the right-handed system is preferred, with the origin at the center of the reference space (center of the world, view, display, screen, etc.).  In general, virtual spaces (world, view) can remain unitless, but physical spaces (display, screen) are inherently pixelated, with physical (metric) dimensions.

Reference Space and Transforms

The classes in this package have no inherent reference space.  The client is free to use them it whatever reference space is needed.  Typically, there is need to transform objects from one reference space to another, such as from world to view space, or from the local space of some shape within a nested shape to the world space.  Many, but not all, classes in this package provide for such transformations, using the Matrix4 class.

Data Classes

The data classes in this package are specially constructed to allow immutability and extension. In general, extending a data class means imposing constraints on the state of the class, such as immutability, or maintaining a vector in a normalized state.

Implementation

Master mutators, accessors, and initializers in the lowest level data classes are named impl??? (for implementation), and are declared protected.  This allows sub-classes to easily hook into the base class to impose constraints, but it also exposes the base class to potential harm.  Great care must be exercised in overriding such implementation methods to assure that the super class method is called, and any constraints on the subclass also apply to the base class methods.  Higher level data classes do not use explicit implementation methods, for simplicity, but do note wh which methods are master mutators and accessors.

Constructors require special attention since they may or may not require that the constraints of the subclass be imposed on the initial state of a new object. Unless otherwise stated, constructors should use local mutators to initialize state, which assures that all constraints of the class are imposed on the class and any subclasses. For special situations, such as initializing an immutable subclass, implementation initializers allow direct initialization of the super class state without interference from overridden mutators.

Note that a distinction is made between full and partial state mutators and accessors.  This distinction is an important one if a constraint applies to the whole state rather than its individual state elements.  For example, a normalized vector class would apply the normalization constraint on the whole state, and reject any attempt to set partial state.  A point class that limits the extent of its value, however, could apply the constraint on an element-by-element basis.

All other mutators and accessors in the data classes are declared final if other methods in the data class use them.  This allows the data class to conveniently use its own methods while preventing subclasses from inadvertently breaking the base class by casually overriding them.  In the future, as the need arises, data classes can be refactored to only use their implementation methods, which would allow the final declarations to be removed.

Immutability

The classes are designed to allow the option of immutability.  As such, all fields are private; all mutators are carefully defined and limited; and, most classes include a lazily built immutable version of itself.  Also, mutators use defensive copies of all input parameters, and accessors use a return value object with a copy of the requested data.

An immutable view of a data object is created by extending the class as a wrapper with all impl??? mutator methods throwing an UnsupportedOperationException, and all accessor methods calling through to the target (wrapped) object..

Garbage Collection

Data class design attempts to minimize the the creation of many small objects, which can impact interactive performance when theyare garbage collected.  Great use is made of immutable views, return value objects, and internal dummy objects. If possible, accessors return an immutable view of an object; otherwise, they and utility methods use a return value object supplied by the client to return the requested value.  For operations requiring intermediate internal results, object and class dummy variables are often used.

Thread Safety

No care has been taken to make the classes threadsafe. The use of dummy variables for implementation complicates the matter and makes an efficient threadsafe implementation difficult.  As the need arises, data classes can be refactored to not use dummy variables and methods can be synchronized (or synchronized wrappers can be created).  Immutable versions of the classes, however, are inherently threadsafe.