net.refractions.udig.project.render
Interface IRenderer

All Known Subinterfaces:
IMultiLayerRenderer

public interface IRenderer

Used to mark an implementation of RenderImpl.class; responsible for rendering a layer.

A renderer has the following responsibilities:

Since:
0.1
Author:
jeichar

Field Summary
static int CANCELLED
          Indicates that the renderer has been cancelled rendering
static int DISPOSED
          Indicates that the renderer has been disposed and can no longer be used
static int DONE
          Indicates whether the renderer has finished rendering.
static int NEVER
          Indicates that the renderer has been reset and does not have anything to show
static java.lang.String RENDER_EXT
          The name of the Extension Point for Renderers
static int RENDER_REQUEST
          When a renderer sets its state to RENDER_REQUEST that indicates that is needs to be rerendered.
static int RENDERING
          Indicates whether the renderer job is currently running
static int STARTING
          Indicates that the renderer has started rendering but does not have data to be displayed
 
Method Summary
 void dispose()
          Informs the renderer to dispose of resources
 IRenderContext getContext()
          Returns the renderer's context object
 Envelope getRenderBounds()
          Gets the area that will be rendered next.
 int getState()
          Returns the current state of rendering.
 boolean isCacheable()
          Indicates whether the framework is permitted to cache the results of the renderer.
 void render(java.awt.Graphics2D destination, IProgressMonitor monitor)
          Requests the Renderer to render with the graphics2d object
 void render(IProgressMonitor monitor)
          Ask the renderer to update the internal image using the smaller of getRenderBounds() or ViewportBounds.
 void setRenderBounds(Envelope boundsToRender)
          Called to set the area that will be rendered.
 

Field Detail

RENDER_EXT

static final java.lang.String RENDER_EXT
The name of the Extension Point for Renderers

See Also:
Constant Field Values

NEVER

static final int NEVER
Indicates that the renderer has been reset and does not have anything to show

See Also:
Constant Field Values

RENDERING

static final int RENDERING
Indicates whether the renderer job is currently running

See Also:
Constant Field Values

DONE

static final int DONE
Indicates whether the renderer has finished rendering.

This implies that rendering has started and finished

See Also:
Constant Field Values

DISPOSED

static final int DISPOSED
Indicates that the renderer has been disposed and can no longer be used

See Also:
Constant Field Values

STARTING

static final int STARTING
Indicates that the renderer has started rendering but does not have data to be displayed

See Also:
Constant Field Values

CANCELLED

static final int CANCELLED
Indicates that the renderer has been cancelled rendering

See Also:
Constant Field Values

RENDER_REQUEST

static final int RENDER_REQUEST
When a renderer sets its state to RENDER_REQUEST that indicates that is needs to be rerendered. The container of the renderer(usually a renderExecutor) will respond by calling render. This is done so that the container can include run the renderer in a thread seperate from the one that called setState().

setRenderBounds(Envelope) can be called to set the area that needs to be rendered}

See Also:
Constant Field Values
Method Detail

getState

int getState()
Returns the current state of rendering.

The state is the current state of the org.eclipse.core.runtime.jobs.Job

Options are:

Returns:
the current state of rendering.

render

void render(java.awt.Graphics2D destination,
            IProgressMonitor monitor)
            throws RenderException
Requests the Renderer to render with the graphics2d object

This method will block

Parameters:
destination - The objects that the Renderer will use for rendering
Throws:
RenderException

render

void render(IProgressMonitor monitor)
            throws RenderException
Ask the renderer to update the internal image using the smaller of getRenderBounds() or ViewportBounds.

Render State

Normally the RenderManager will update the screen every second. However if the renderer has data that must be displayed then it can call setState(RENDERING) and the Screen will be updated immediately. This should be called with care however since many such calls can cause performance problems.

Internal Image

The RenderContext maintains an "internal image" that you can access using getContext().getGraphics(); you can use Image.createGraphics() to retrive a Graphics2d to draw with. Example Implementation:

 public void render( IProgressMonitor monitor ) throws RenderException {
     if( monitor == null ) monitor = NullProgressMonitor();
     Graphics2D g = getContext().getImage().createGraphics();
     render(g, monitor);
 }   
 

Updating a Portion of the Screen

When the envelope (ie getRenderBounds()) is smaller than the ViewportBounds, the rendered area DOES NOT TAKE UP THE WHOLE MapDisplay. It only takes up the area that the envelope would map to. The purpose of this functionality is to allows only a small area of the MapDisplay to be refreshed rather than the whole area.

Please choose the smallest of:

Throws:
RenderException
See Also:
getContext(), IRenderContext.getImage(),

This method will block

A value of null renders the bounds the entire viewport obtained from the ViewportModel.getBounds().


getContext

IRenderContext getContext()
Returns the renderer's context object

Returns:
the the renderer's context object
See Also:
IRenderContext

dispose

void dispose()
Informs the renderer to dispose of resources


isCacheable

boolean isCacheable()
Indicates whether the framework is permitted to cache the results of the renderer.

Returns:
true if the framework may cache the resulting image and only request the new dirty areas.

setRenderBounds

void setRenderBounds(Envelope boundsToRender)
Called to set the area that will be rendered.


getRenderBounds

Envelope getRenderBounds()
Gets the area that will be rendered next.

Please make use of the smaller of getRenderBounds() or the viewport bounds when rendering.

Returns:
bounds to be drawn next