Apparance Logo

Everything you need to know about the user interface, the controls, and the procedure editing process.

Apparance Editor

The Apparance Editor is the place where all creative magic happens. Build up a library of procedures to describe your world and its content. Explore the parameter space they occupy, tweaking and playing to home in on the look you are after.

Editor

Windows

The editor currently operates in a single window with multiple fixed panels. These panels are:

  • Operator Browser - Find/manage procedures and operators
  • Procedure Graph - Wire up procedures
  • Property Editor - Tweak properties and constants
  • 3D View - See generated geometry

Functionality

The main functionality provided by the editor application is:

  • Creating - Author hierarchies of procedures to build geometry
  • Viewing - Exploring the synthesised worlds and objects in 3D
  • Playing - Adjusting parameters interactively to see where it takes you

Browser

The browser panels (to the left) are where all the loaded procedures and built-in operators can be found. Explore, search, and then drag from here to assemble your procedures.

Procedures

Procedures are at the heart of Apparance, these are your content, your design, your objects, and your world. By carefully organising and managing your procedures you can build up a hugely complex and detailed worlds with ease. Procedures are grouped by category and then listed alphabetically by name. A naming convention the browser uses to help organise procedures is to separate sub-levels with dots, for example House.Window would be at the same level as House.Door in the hierarchy. Any part of a name before a dot will appear faded in the browser to help see the unique parts beneath. Whilst categories correspond to separate directories on disk, the naming hierarchy is simply a naming convention and forms the procedure file name.

Operators

Operators are navigated and used exactly the same way as procedures, but they are implemented in code instead of data. The operators you see available are built in to the engine and provide the fundamental functionality of it. Operators have a display name and an internal name, the display name you see on the placed operator and describes its purpose, the internal name disambiguates it from variants (usually by the type it operates on or number of inputs). Operators are grouped by category and then listed alphabetically by their internal name (followed by the display name). A full list of Operators is provided on the operators page of the manual.

Procedure Graph

The main editor window is occupied by the procedure graph, a visualisation of the operators and interconnections between them that make up a procedure. The left side of the procedure outline hosts the input connection points for the procedure, the right, the outputs.

Each Operator within the procedure similarly shows its inputs on the left and outputs on the right. Most are named and have tool-tips to help you remember what each is for. Here is an example, hover over the connections to learn more about them.

The data type for all connection points and the wiring between them are indicated by their colour to help visualise the kinds of information flowing through the procedures. Here is a summary of the types available and their colours.

Property Panel

Many objects in the editor have properties that are exposed for editing via the property panel to the right of the UI. The most common ones are the operators placed in a procedure. By selecting an operator, it's inputs are listed, with editing controls appropriate for each type. A procedures input and output names and descriptions can also be edited here.

Most controls are pretty standard for property editing, but a few are extended to provide extra useful functionality. The colour edit control shows separate RGB sliders and a colour preview swatch. The integer and floating point edit controls have sliders with configurable min and max values. Enumeration and flag properties sometimes have button panels for all their options.

3D View

To the top-right is a small 3D preview window where any generated geometry is displayed via the built in rendering engine. This includes a ground plane grid, camera controls, and a plethora of configurable display options for diagnosing generation and rendering problems.

Camera

The view-point the 3D scene is rendered from can be adjusted to allow exploration and investigation of your scene and models. By default this starts looking at the world origin (0,0,0). The camera position and settings is remembered for each procedure you view so as you switch between them you return to where you were last looking from.

Controls

The camera is controlled either by keyboard and mouse, supporting several operation modes, or by an Xbox 360 controller (plugged into a USB socket).

The most common way to control the camera is with 'quake' style FPS controls.

  • RightMouse look (hold during camera movement)
  • W/SForward / backward (relative to camera look direction
  • A/DLeft / Right (relative to camera look direction)
  • Q/EUp / Down (relative to camera look direction)
  • WheelMovement speed (up slower, down faster)

You can also use a control method similar to many 3D modelling packages.

  • MiddlePan, hold to pan the view relative to camera look direction
  • Alt+MiddleOrbit, hold to orbit around the point of interest (always a certain distance in front of the camera)
  • Shift+MiddleSlide, hold to slide along parallel to the ground plane
  • Ctrl+MiddleElevation, hold to raise and lower the camera vertically (relative to the world)
  • WheelAdjust interest distance, the distance to the point of interest (up nearer, down farther)

Using an Xbox controller is a nice way to explore your creations as it provides a smoother movement and analogue speed controls.

  • Left StickMovement : Forward/backward movement and left/right strafe control
  • Right StickLook : Control look direction
  • Left TriggerDown : Move down vertically (relative to the world)
  • Right TriggerUp : Move up vertically (relative to the world)
  • Left BumperSlower : Decrease movement speed
  • Right BumperFaster : Increase movement speed
  • D-pad DownReset : Reset camera to initial/stored position (see Camera Reset)

At the moment, there is also a 'carousel' viewing mode where the camera slowly rotates around the current camera point of interest.

  • LeftAuto-rotate : Click the mouse in the viewport to toggle carousel mode

Some camera movements will also cancel carousel mode.

Grid

The 3D view, by default, has a ground-plane grid to help get your bearings and to visually size up objects. There are a few configurable options available to customise and control the grid available by pressing the Grid button at the top-right of the viewport.

  • Enable - The whole grid can be turned on and off
  • Axis - The axis indicator can be turned on and off
  • Size - How far the grid extends away from the origin
  • Intensity - The darkness of the grid can be adjusted

TipThe grid is implemented as just another procedure, the settings you see are just the default inputs used to generate it with. Search for it in the procedure browser, and have a tweak.

Diagnostic Camera

Some of the renderer behaviour is linked to the position of the camera, and fundamentally, the engine is busy building the world best suited for your particular point of view. The diagnostics camera mode allows you to 'step outside' the normal point of view, and see what's actually going on around you. When in this mode, the camera position the engine bases its work on is frozen and separated from the actual viewpoint being rendered. This means you can properly inspect up close many things such as distant low-detail geometry, the detail banding and transition regions, detail switching decisions, the various colourising diagnostics modes, all without the engine updating the scene to follow the camera. When in diagnostics camera mode, the real camera frustum is rendered with white lines. There are frame bounds rectangles at 1, 10, 100, and 1000 units away from the camera centre.

Expanded View

For many procedure building tasks, the small 3D view is sufficient to monitor progress, but when you want to see things in more detail you can switch to an expanded view mode.

  • SpaceToggle expanded 3D view : Toggles between normal small preview window in top right and larger extended view overlaying the procedure graph and browser.

This mode moves the 3D viewport to cover the procedure graph and browser panels, expanding the property viewer to occupy the whole right hand side.

This state is good for tuning parameters interactively as you get better visual feedback in the larger view.


Managing Procedures

Each procedure is stored in it's own file on disk as a .proc file, along with data that is only used by the editor in a .procedit file. Each procedure is represented by an entry in the procedure browser.

Organisation

Each procedure has a category and a name, with procedures of the same category appearing under the same section heading in the browser. The names can contain any characters that are acceptable in a filename and appear as an alphabetically sorted list. If you use full-stops to delineate nested levels of procedure naming then the editor will use this to help visualise this ad-hoc hierarchy by making the name part before the last dot fainter. This has the effect of indenting names that share the same prefix together.

Creating New

  • Alt+NNew Procedure : Creates a new, empty procedure, called new procedure in the same category as the selected procedure.

You will need to have a procedure selected (Left) under the category you want to add the new one to.

Renaming/Moving

Procedures can be easily renamed, without affecting any of your procedures functionality (they are referenced by immutable unique identifiers internally).

  1. LeftSelect the procedure you want to rename
  2. The category, name, and description of the procedure are presented in the Property Panel.
  3. Edit the name and description.
  4. The changes are applied when the text entry field loses focus (either Left click the mouse somewhere else or press Tab).
  5. The procedure will update, and be marked as edited.

To move a procedure change the procedures category property and the procedure browser will show it in the new location.

Other Properties

A procedures description property is a really useful place to document the use of the procedure. This will appear as a tooltip on any instance of the procedure you hover the mouse pointer over.

Saving & Loading

  • Ctrl+SSave the project and all edited procedures
  • You can also press the Save button at the top-left of the editor window.

All procedures are saved and loaded together, you can't partially save the project or individually save procedures.

TipA backup history of every procedure saved is maintained in a backup directory alongside the procedure data files. This is purely maintained for emergency, hand maintenance, and not available within the editor. Procedure files are very small so there should be no need to clean out backups.
NoteIf there is a long synthesis job going on in the background (egg-timer visible in top-right of procedure edit window) then the save operation may be delayed momentarily until it is completed.
WarningApparance doesn't warn of unsaved changes on exit at the moment, please make sure you have saved your work before closing the editor

Viewing

To view a geometry generating procedure in the 3D view LeftSelect the procedure in the procedure browser and press the View button at the top left of the UI.

  • ViewView Procedure button switches the 3D view to generating and showing that procedures output

The currently viewed procedure name is shown in the top-left information panel.

The view camera will be restored to the position it was in the last time you viewed a particular procedure.

TipF5Refresh will force re-synthesis of the current procedure. Normally not needed during modelling as the view updates automatically.
NoteIt's important to note here that any procedure can be synthesised using the 'view' button, it just depends on what outputs it has that affect how it can be used.

At the moment it's only really geometry outputs (white Model Segment pins) that produce anything practical, it's these outputs that are added to the scene to view in the 3D view.

The Web-site project does have outputs, but these are just used to drive the propagation of information through the procedure graph. Each Site.* procedure has a string output which happens to produce the path of the generated page. This isn't particularly relevant to the process though as all the actual work is done with file IO, reading, composing, compiling, generating, writing, and copying files. The output does however signify success.

WarningAt the moment non-geometry procedure outputs can only be seen in the debug output stream with a debugger attached. Please feel free to try this as you will also be able to see live logging output too.

When you view a procedure with inputs, these adopt the default values set on the input properties.

  • LeftSelect the procedure in the procedure browser to view its inputs and their default values in the property panel.

These input values serve three purposes:

  1. To provide sensible values when viewing the procedure on its own.
  2. To allow you to test procedures in isolation and play with the inputs.
  3. To provide initial values when you place one down as an operator in another procedure.

TipThe general workflow for showing off procedures is: select procedure in browser, toggle to large view, play with input parameters in property panel.

The viewed procedure field in the information panel is actually a text box that you can type in the name of the procedure to view. It accepts * and ? wildcards too allowing multiple procedures to be evaluated together. This was added to support background updating of multiple pages of the web-site whilst it was being worked on since changes to shared procedures can affect more than one page. This is used in conjunction with the watch field of the information panel which allows selection of a directory to watch for changes. When a file change is detected the currently 'viewed' procedures are re-built.

This was required to speed up web page content iteration by watching for changes in the source markdown documents, which are edited externally, and using them to trigger an update. In conjunction with the LivePage plugin for the Chrome browser this provides an end-to-end live-editing of page content pipeline. Every time I hit save in notepad I see the web page update. You can see this in action in a video demonstration of live web-site editing I put together.

Opening

To open a procedure in the main procedure graph panel for inspection or editing you can either:

  1. DoubleclickOpen procedure from the procedure browser.
  2. DoubleclickOpen procedure from an instance of the procedure in a procedure graph.

The currently edited procedure is highlighted in the procedure browser and has its name shown in the top-left information panel.


Editing Procedures

The normal workflow when editing procedures will include:

  1. Navigating around the procedure graph
  2. Selecting operator instances
  3. Wiring operators together
  4. Setting constant values
  5. Adding inputs and outputs to the procedure

The procedure graph view area can be panned and zoomed to see the procedure, its operator instances, and its wiring close-up, or as an overview.

  • RightPan to drag the view around the viewport.
  • WheelZoom in and out on the procedure.

Anatomy

The procedure graph editor consists of several distinct areas and contains various important elements:

Bounds

The boundary of the procedure is host to the input points on the left, the output points on the right, and the full procedure name at the top.

You can't explicitly adjust the size of the bounds, but it will expand to accomodate the operators within it. You can extend the boundary in any direction by moving an operator instance near it.
WarningThere is currently no way to shrink the boundary back down it can only be expanded

Inputs

The left hand side of a procedure shows its inputs.

Outputs

The right hand side of a procedure shows its outputs.

Operators

The main area within a procedure is where all the functionality lives. Fundamental operators (dark grey) and other procedures (light grey) can be dropped in here for wiring up.

Each operator (or procedure) instance shows its inputs and outputs in a similar way to the procedure itself. For a full list of the available procedures see the operator directory.

Wiring

All the

Notes

Notes (not shown) are for two things: adding descriptive and explanatory text, and grouping operators together.

Selection and manipulation of notes is slightly different from standard because of the various states they can be in.

  1. Inactive - No normal mouse operations interact with the note, effectively procedure background.
  • DoubleclickActivate Note and enable movement
  1. Active - Note can be resized, and moved (along with its contents).

Hovering over the corners, edges, and inside of the note show the manipulation available.

  • Drag cornerResize the note in that direction
  • Drag edgeResize the note in that direction
  • Drag insideMove the note and it's contents around the procedure
  • ClickDeactivate by clicking on the procedure background to return the note to its inactive state
  • DoubleclickEdit Note to switch to editing mode
  1. Editable - Note heading and body text can be edited (they are text entry fields)
  • ClickChoose to edit the heading or note body text
  • Tab and Shift+Tab to switch between heading and body
  • ClickDeactivate by clicking on the procedure background to return the note to its inactive state

Selection

Various elements in the procedure editing window are selectable, for either moving around or for viewing and editing properties. Most of them also high-light when the mouse pointer is over them to provide additional feedback.

  • Operator instances
  • Procedure input collection
  • Procedure output collection
  • Notes

For most of these the selection mechanic is fairly standard:

  • LeftSelect an operator, deselecting all others
  • DragMarquee Select around operators, selecting them all
  • Ctrl+LeftToggle Selection on individual operators
  • LeftDeselect all by clicking on the procedure background

The procedure input/output areas to the left/right of the procedure boundary are selectable as a whole, just click outside the boundary anywhere that isn't an input/output label.

Operators & Procedures

Operators and procedures, once placed down, are treated exactly the same way. Where the term 'Operator' is used here it applies to Procedures too.

Adding

Operators are added to the procedure graph by dragging from the browser onto a blank space.

  • DragPlace new operator/procedure instance

Positioning

Operators can be arranged within the procedure as best befits their place in the process they are wired up into. Selecting multiple operators allows them to be moved together.

  • DragMove selected operators around the procedure

Operators that have been placed within the border of a note turns the note into a group, i.e. becomes 'attached' to the note. When the note is moved, all the operators placed on it move too.

  • Double ClickActivate group of operators
  • DragGroup to move with all operators in the group

NoteOperators are only added to a group if they are dropped within a group border. Moving a group to be underneath an operator does not add it to the group.

As operators are moved, all wiring is updated to stay connected and the boundary of the procedure may be expanded to accomodate their positions.

Removing

Operators can be removed by selecting them and then pressing Delete.

  • DeleteDelete selected operator(s)

Wiring

The interconnections between operators and input/output points are generally termed 'wires'. Wires always connect from one point to another point within a procedure, i.e. they have direction. Because there are two types of things that a wire can come from both: one of the procedures inputs and one of the operators outputs it's confusing to use the terms 'input' and 'output' when talking about direction of information flow. Because of this we use the term 'Source' and 'Sink' to mean 'a provider of information' and 'a consumer of information'. Summarised here:

Wires signify which Sinks will take their values from which Sources. Source and Sink points are illustrated by the small right-pointing triangles of various colours on the Operators and at the Procedure inputs and outputs.

There are several wiring operations that can be performed:

  • Make - Connect a Source and a Sink together
  • Break - Disconnect an existing Source-Sink connection
  • Move - Change one Source or Sink connection to another Source or Sink

To make a connection:

  1. Lefton Source/Sink to connect starting from the name label or triangular marker.
  2. Dragto required Sink/Source over the name label or triangular marker. Compatible connection points will highlight in bright green. Wire end will 'lock on' to the connection point.
  3. Releaseto make the connection with the chosen connection point. Letting go when not over a connection point will cancel the connection.

To break a connection:

  1. Hoverover end of wire to disconnect and it will highlight in white (whole wire will appear bold).
  2. Dragthe wire end off of the connection point it is connected to.
  3. Releaseaway from connection point to remove the connection.

To move a connection:

  1. Hoverover end of wire to move and it will highlight in white (whole wire will appear bold).
  2. Dragthe wire end away from the connection point it is connected to.
  3. Dragto the new connection point over the name label or trianguoar marker. Compativle connection points will highlight in bright green. Wire end will 'lock on' to the connection point.
  4. Releaseto break the old connection and make the new one

Constants

Unconnected Sinks assume constant values. These can be chosen and adjusted interactively in the editor. Operators behave exactly the same way as if they are wired to something that happened to always produce a certain value.

Editing Operator input constants:

  1. LeftSelect the Operator
  2. Propertyedit the value using the property panel

Many of the data types have special editing UI which will appear in the property panel for them.

Inputs

The left edge of a procedure holds its inputs. These are added to provide ways to parameterise the logic wired up within.

Adding

To add an input simply drag a connection from a Sink somewhere in the procedure, such as an operator input, past the LEFT edge of the procedure. This creates a new input of the type matching the chosen Sink, i.e. to create a string input, drag a string connection out of the left side.

  1. LeftStart new connection from an existing sink of the right type
  2. DragTo input area on the LEFT side of the procedure
  3. DropCreate new input by dropping on the input area

See below for instructions on changing the name of the input.

NoteDoing this will update any places where the procedure is already used to have the additional input and assign it the default value for the given type
TipIt doesn't matter which connection point you use, as long as it's the right type. You can easily disconnect it for connection to the correct point later.

Removing

WarningUnfortunately at the moment there isn't a way to remove inputs, although in some circumstances you can use Undo to remove an accidentally created one. Sorry. NOTE: Only do this if the procedure isn't being used within another procedure. If you are unsure, see Tip below.
TipIf you accidentally create an input, or decide you don't want it any more, the best plan is to just rename it something like an underscore "_" and ignore it.

Properties

Inputs can be renamed and have helpful descriptions added. Select the input area (highlights in yellow), and edit using the Property Panel on the right.

  1. LeftSelect the input area on the LEFT to see the inputs listed in the Property Panel.
  2. PropertyEdit Name & Description for each input in Property Panel.

Outputs

The right edge of a procedure holds its outputs. These are added to provide ways to pass information out from, the logic wired up within.

Adding

To add an output simply drag a connection from a Source somewhere in the procedure, such as an operator output, past the RIGHT edge of the procedure. This creates a new output of the type matching the chosen Source, i.e. to create a string output, drag a string connection out of the right side.

  1. LeftStart new connection from an existing source of the right type
  2. DragTo output area on the RIGHT side of the procedure
  3. DropCreate new output by dropping on the output area

See below for instructions on changing the name of the output.

NoteDoing this will update any places where the procedure is already used to have the additional output (unconnected)
TipIt doesn't matter which connection point you use, as long as it's the right type. You can easily disconnect it for connection to the correct point later.

Removing

WarningUnfortunately at the moment there isn't a way to remove outputs, although in some circumstances you can use Undo to remove an accidentally created one. Sorry. NOTE: Only do this if the procedure isn't being used within another procedure. If you are unsure, see Tip below.
TipIf you accidentally create an output, or decide you don't want it any more, the best plan is to just rename it something like an underscore "_" and ignore it.

Properties

Outputs can be renamed and have helpful descriptions added. Select the output area (highlights in yellow), and edit using the Property Panel on the right.

  1. LeftSelect the output area on the RIGHT to see the outputs listed in the Property Panel.
  2. PropertyEdit Name & Description for each output in Property Panel.

Undo & Redo

The Apparance Editor is built with a full command based system internally and supports Undo and Redo of most editing operations.

  • Ctrl+ZUndo to undo the last edit operation
  • Ctrl+Shift+ZRe-do to re-perform the most recently un-done operation
  • Ctrl+YRe-do to re-perform the most recently un-done operation

Operations supported include, but not limited to:

  • Adding/removing operators
  • Operator re-arrangement (moving)
  • Wiring operations (make/break/move)
  • All procedure property editing (including naming and comments)
  • Adding procedure inputs/outputs (see caveats above)