LegendKit Class Reference

The LegendKit class is used to draw a simple colormap legend. More...

#include <LegendKit.h>

Inheritance diagram for LegendKit:

Public Types
typedef SbString	SoNumberFormatCB(const double number, void *closure)

Public Member Functions
	LegendKit (void)
void	addBigTick (double nval, const SbString &string, const SbString *discretestring=NULL)
void	addBigTick (double nval, double tickvalue, const SbString *discretestring=NULL)
void	addDiscreteColor (double uppernval)
void	addDiscreteColor (double uppernval, uint32_t color)
void	addSmallTick (double nval)
void	clearData (void)
void	clearTicks (void)
void	enableBackground (const SbBool onoff)
void	enableImage (const SbBool onoff)
float	getLegendWidth (void) const
void	preRender (SoAction *action)
void	setBackgroundColor (const SbColor &color, const float transparency=0.0f)
void	setColorCB (uint32_t(*colorCB)(double))
void	setColorCB (uint32_t(*colorCB)(double, void *), void *userdata=NULL)
void	setDiscreteMode (const SbBool onoff)
void	setImageTransparency (const float transparency=0.0f)
void	setNumberFormatCallback (SoNumberFormatCB *cb, void *closure)
void	setPosition (const SbVec2s &pos)
void	setTextColor (const SbColor &color, const float transparency=0.0f)
void	setTickAndLinesColor (const SbColor &color, const float transparency=0.0f)
void	useTextureNotImage (const SbBool onoff)

Static Public Member Functions
static void	initClass (void)

Public Attributes
SoSFFloat	bigTickSize
SoSFBool	delayedRender
SoMFString	description
SoSFBool	descriptionOnTop
SoSFBool	discreteUseLower
SoSFFloat	imageWidth
SoSFBool	on
SoSFFloat	smallTickSize
SoSFFloat	space
SoSFBool	threadSafe
SoSFString	tickValueFormat
SoSFFloat	tickValueOffset
SoSFFloat	topSpace

Protected Member Functions
virtual	~LegendKit ()
virtual SbBool	affectsState (void) const
virtual void	audioRender (SoAudioRenderAction *action)
virtual void	callback (SoCallbackAction *action)
virtual void	getBoundingBox (SoGetBoundingBoxAction *action)
virtual void	getMatrix (SoGetMatrixAction *action)
virtual void	getPrimitiveCount (SoGetPrimitiveCountAction *action)
virtual void	GLRender (SoGLRenderAction *action)
virtual void	handleEvent (SoHandleEventAction *action)
virtual void	notify (SoNotList *list)
virtual void	pick (SoPickAction *action)
virtual void	rayPick (SoRayPickAction *action)
virtual void	search (SoSearchAction *action)

Detailed Description

The LegendKit class is used to draw a simple colormap legend.

FIXME: there should be an explanation of general usage here, preferably with an example. 20040305 mortene.

The class is organized as a nodekit for convenience. Most parts are public, but users should seldom have any reason for changing anything but the backgroundMaterial, tickMaterial and extraNodes parts.

This nodekit contains the following parts:

• topSeparator The separator that holds all subscene for this kit. Private.

• resetTransform Used to reset any transform that might be on the state

• viewport Used to set the viewport for the legend. Contains a ViewportRegion node. This part is NULL by default. Set this part if you want to restrict the area the legend is drawn into.

• depthBuffer Used to disable depth buffer tests. Contains a DepthBuffer node.

• lightModel Used to disable lighting. Contains an SoLightModel node.

• camera Contains an SoOrthographicCamera, which defines the view volume for the shapes in the kit.

• position Can be used to move the legend from the lower left corner. The coordinate system of this node is one unit per pixel. This part is NULL by default, but a SoTranslation node can be inserted here.

• texture Its only purpose is to disable texturing. Contains an SoTexture2 node.

• shapeHints Contains an SoShapeHints node, and sets default shape hints. This is needed to render the shapes in this kit correctly.

• backgroundMaterial Might be used to change the background color. Contains an SoMaterial node.

• backgroundShape Contains the shape (SoIndexedFaceSet) that renders the background frame. This is rendered as four quads surrounding the image. Set this part to NULL if you don't want a background frame.

• imageSeparator A separator that holds nodes needed to render the image. Private.

• imageTransform Applies a transformation to the image to account for image offset. Will be set in LegendKit::initLegend().

• imageMaterial Is used to reset the material to default before the image is rendered. Contains a default SoMaterial node by default. Will only take effect if you render the image a a textured quad.

• imageSwitch Is used to switch between image rendered as a raw image (whichChild = 0), or rendered as a textured quad (whichChild = 1). This is useful since some 3D hardware might render raw images very slowly. Default value is 0, and you can set this value using Legendkit::useTextureNotImage().

• image Hold the raw image data for the legend as an SoImage node.

• textureGroup A group used to hold the texture image and shape.

• textureImage A one row texture used when rendering the image as a textured quad.

• textureShape An SoFaceSet that renders one quad.

• tickMaterial Can be used to set the material of the ticks and lines. In the default node, diffuse color is set to (0 0 0).

• renderCallbackLines Is used to render ticks and other lines using OpenGL.

• textMaterial Can be used to set the material of the text. This part is NULL by default, and the text will then be rendered in the same color as the ticks and lines.

• renderCallbackText Is used to render text using OpenGL.

• extraNodes Is NULL by default, but can be used to add geometry that can be rendered after all other geometry in this kit. Please note that the coordinate system in the legend is one unit per pixel. This means that the world position (32.0f, 32.0f) is at pixel position (32,32) in the legend viewport.

Constructor & Destructor Documentation

LegendKit()

LegendKit::LegendKit

(

void

)

Constructor.

~LegendKit()

LegendKit::~LegendKit ( )

protectedvirtual

Destructor.

Member Function Documentation

addBigTick() [1/2]

void LegendKit::addBigTick	(	double	nval,
		const SbString &	string,
		const SbString *	discretetext = NULL )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

addBigTick() [2/2]

void LegendKit::addBigTick	(	double	nval,
		double	tickvalue,
		const SbString *	discretetext = NULL )

Adds a big tick at the normalized (0-1) position nval. Prints the value tickvalue to the right of the tick. If discretetext is != NULL, this text will be used when in discrete mode, and will be printed between this tick and the previous tick.

addDiscreteColor() [1/2]

void LegendKit::addDiscreteColor

(

double

uppernval

)

Adds a discrete color. The area from the previous discrete color added (or from 0 if this is the first one) to uppernval will be painted with the color found from the color callback for the value uppernval or from the previous discrete uppernval if discreteUseLower is TRUE.

addDiscreteColor() [2/2]

void LegendKit::addDiscreteColor	(	double	uppernval,
		uint32_t	color )

Adds a discrete color. The area from the previous discrete color added (or from 0 if this is the first one) to uppernval will be painted with color.

addSmallTick()

void LegendKit::addSmallTick

(

double

nval

)

Adds a small tick at the normalized (0-1) position nval.

clearData()

void LegendKit::clearData

(

void

)

Clears all data in this kit.

clearTicks()

void LegendKit::clearTicks

(

void

)

Clear all tick information.

enableBackground()

void LegendKit::enableBackground

(

const SbBool

onoff

)

Enables or disables the legend background.

enableImage()

void LegendKit::enableImage

(

const SbBool

onoff

)

Enable/disable legend image. Is enabled by default.

getLegendWidth()

float LegendKit::getLegendWidth

(

void

)

const

Returns the width (in pixels) of the legend.

GLRender()

void LegendKit::GLRender ( SoGLRenderAction * action )

protectedvirtual

Overloaded to (re)initialize image and other data before rendering.

initClass()

void LegendKit::initClass ( void )

static

Initializes this class. Call before using it.

notify()

void LegendKit::notify ( SoNotList * list )

protectedvirtual

Overloaded to recalculate stuff when necessary.

preRender()

void LegendKit::preRender

(

SoAction *

action

)

Method needed for thread safe rendering. If multiple threads are used to render a scene graph containing this nodekit, you must set the threadSafe field to TRUE, and use an SoCallbackAction to call this method before rendering the scene graph.

setBackgroundColor()

void LegendKit::setBackgroundColor	(	const SbColor &	color,
		const float	transparency = 0.0f )

Sets the background color.

setColorCB()

void LegendKit::setColorCB	(	uint32_t(*)(double, void *)	colorCB,
		void *	userdata = NULL )

Sets the callback used to decide the color per line in the image.

The user-provided callback should for each call return the RGBA value encoded as a 32-bits value, for the value given by the first argument to the callback.

setDiscreteMode()

void LegendKit::setDiscreteMode

(

const SbBool

onoff

)

Switch to discrete mode. If a callback is registered and one or more big ticks have been added, a call to this method will cause the discrete data to generated based on those values. For each big tick, the color value is found, and the discrete color for the area from the tick to the next big tick is set to the color of the line right under the next big tick.

setImageTransparency()

void LegendKit::setImageTransparency

(

const float

transparency = 0.0f

)

Sets the transparency for the image in the legend (the color bars). Because the image might be drawn as an image, and not a texture, each pixel in the image has to be reset to the new alpha value the next time the legend is rendered.

setNumberFormatCallback()

void LegendKit::setNumberFormatCallback	(	SoNumberFormatCB *	cb,
		void *	closure )

Set a callback to be used for formatting numbers instead of the tickValueFormat field.

setPosition()

void LegendKit::setPosition

(

const SbVec2s &

pos

)

Sets the position, in pixels from the lower left corner of the GL widget.

setTextColor()

void LegendKit::setTextColor	(	const SbColor &	color,
		const float	transparency = 0.0f )

Sets the color used when rendering text.

setTickAndLinesColor()

void LegendKit::setTickAndLinesColor	(	const SbColor &	color,
		const float	transparency = 0.0f )

Sets the color used when rendering ticks and other lines.

useTextureNotImage()

void LegendKit::useTextureNotImage

(

const SbBool

onoff

)

By default the image is drawn as a raw GL image. Call this with onoff TRUE if you want to use a textured quad instead. This is much faster on most PC cards. Maybe a test for linux and _WIN32 could be a good idea to enable this. On SGI and HP (AFAIK) platforms raw GL image drawing is pretty fast.

Member Data Documentation

bigTickSize

SoSFFloat LegendKit::bigTickSize

The size of the big ticks, in pixels.

delayedRender

SoSFBool LegendKit::delayedRender

Specifies whether legend should be rendered using SoGLRenderAction::addDelayedPath(). Default value is TRUE.

description

SoSFString LegendKit::description

The description/title for the legend. Default value is an empty string. If you specify several strings, they will be printed one string per line.

descriptionOnTop

SoSFBool LegendKit::descriptionOnTop

Specifies whether description should be on top or at the bottom. Default value is TRUE.

discreteUseLower

SoSFFloat LegendKit::discreteUseLower

When calculating the discrete color between big ticks, use the lower value of that section (the value right above the previous big tick), instead of the upper value (the value right below the current bigtick).

imageWidth

SoSFFloat LegendKit::imageWidth

The width of the legend image. Default value is 32.

on

SoSFBool LegendKit::on

Specifies whether the legend is enabled (visible) or not. Default value is TRUE.

smallTickSize

SoSFFloat LegendKit::smallTickSize

The size of the small ticks, in pixels.

space

SoSFFloat LegendKit::space

The space (in pixels) between items in the legend. Default value is 6.0, which usually looks pretty good.

tickValueFormat

SoSFString LegendKit::tickValueFormat

The format string used to convert the tick value into a string. Default value is g.

tickValueOffset

SoSFFloat LegendKit::tickValueOffset

The offset from the end of the big tick to the printed value. Default value is 2.

topSpace

SoSFFloat LegendKit::topSpace

The distance, in pixels, from the top of the viewport to the top of the legend. Default value is 0.0.

---

The documentation for this class was generated from the following files:

• LegendKit.h
• LegendKit.cpp