Geo Generator Design Overview

Overview

Titles in RPITS are defined by templates which consist of lists of geos. "Geo" in this context refers to geometry -- templates are made up of pieces of geometry, each with their own attributes which are sourced sourced from the template's XML and are then overridden by title-specific attributes stored in the database. Most older templates consist entirely of primitive geos, "primitives", which draw one specific element of title on to the canvas. Primitives are defined in imagick_include.php along with a couple helper/utility functions and "building blocks" that assist in the creation of geometry and should not be accessed by a template.

Examples of Primitives are:

• slantRectangle
• blackBox
• plainText
• shadowText
• placeHeadshot
• placeImage
• placeTexture

Examples of Building Blocks:

• fillRectangle
• defaultText

Examples of helper/utility functions

• getTextWidth

Primitives are primarily static -- their attributes are defined in either the template XML or via attribute entries associated with a title in the CDB database. Most primitives expose certain predefined content-oriented attributes directly to the graphics operator via the editing interface. Before being rendered, geo attributes pass through a replacement engine which can give the appearance that their contents are dynamic. Primitives (and, really, all geos) are isolated from each other can cannot change or share values unless they share a replacement string.

For example, it is not possible to define a template using a slantRectangle and a shadowText primitive where the slantRectangle resizes to fit the length of the shadowText.

In order to offer flexibility and ease of use, some titles require a significant amount of logic to determine how they should display. For example, player statscards automatically handle multiple sports, stats (or lack-thereof), headshots, and vital information. This flexibility cannot be written in a template using the current XML based structure. Instead, separate functions called "generators" handle the creation, positioning, and content mapping for subservient geos that are not exposed to the editing interface.

Examples of generators include

• flexBox
• gameSummary
• divingStandings
• weather
• statscard (kind of)*

Geo Structure

All geos (primitives and generators) are loosely defined by simple PHP rendering functions that take two arguments -- $canvas and $o. $canvas is a reference to an Imagick PseudoImage, while $o is an associative array of attributes and their values. The geo rendering interface is purposefully ill-defined; there aren't any strict requirements for attributes or return values nor is any attribute validation performed. Generally speaking, geo functions are expected to modify the canvas within the rectangle bounded by (x,y) and (x+width, y+height).

In order to be rendered and composited on to a title's canvas, an instance of a geo in a template must have an x, y, width, height, and name attribute defined. The value of the name attribute must be unique within a template. One empty/missing name attribute is allowed per title, as the undefined/empty string is a valid value for the name attribute -- this should only be done in single-geo templates. The attribute name order is reserved internally by RPITS and will display an error if used in XML.

During the normal rendering process, the width and height attributes of a geo determine the size of the PseudoImage canvas that will be passed in to the geo's rendering function. The PseudoImage is slightly oversized to allow for overspray resulting from shadows and glow effects. x and y are set to 10 pixels on the pseudoImage, which is then composited on to the Title's canbas at (x-10,y-10). Outside of the "normal" rendering process, such as when called by another geo/generator, geos may be fed a canvas of any size and any x or y values.

Generators

Generators are a subset of geos that perform more than just the composition of one primitive on to a canvas. Since all geos are just arbitrary functions, the classification of a geo as a generator is mostly transparent to upstream rendering operations. Generators must provide their own editing interface in im_edit_title.php. Some of the complex tasks performed by current generators include data acquisition from outside sources (as in gameSummary or weather), data manipulation from other database tables within RPITS (as in statscard or divingStandings), custom/dynamic layout to reflect the size/length/presenece of content or data (flexBox or statscard). All current generators composite multiple primitives on to their canvas.