| Using the Granny Viewer |
|
|
| |||
|
|
The Granny Viewer is a stand-alone application which allows you to view Granny files and inspect their contents. It's primary purpose is as a debugging aid to programmers and artists, so that they can view Granny data outside of their engine for verification, analysis, and inspection.
The entire viewer interface is rendered via your 3D graphics hardware. Since the viewer is meant to be a flexible developers tool, no consideration was given to UI rendering speed, since it is assumed that it will be most commonly run on modern graphics hardware. This means that, if you have an older 3D graphics card, or you have a card which does not have any 3D acceleration, then it will be very difficult for you to run the Granny viewer at an acceptable framerate. This is not a limitation of Granny, only of the viewer application.
The Granny Viewer's user interface is broken up into three panes. The rightmost pane is a vertical bar that contains text-labeled buttons. This is called the "button bar". The other two sections are on the left: one on the top, called the "view" pane, and one on the bottom, called the "listing" pane. They are separated by a draggable divider bar, and each has a set of tabs attached to the top. In addition to these panes, there is also a single-line status bar running along the bottom of the viewer, where the viewer displays information about its current state.
Whenever the entire contents of a pane cannot fit inside its current screen size, you can use the scroll bar to its right to scroll the contents up and down. If you have a mouse wheel, it can be used to scroll the window without using the scroll bar.
In all panes, the left mouse button is the primary action button. It allows you to click on buttons, drag scroll bars, drag dividers, click on tabs, and perform actions in the view pane. Thus, its meaning changes significantly depending on what you are pointing at with the mouse, what mode you have selected, and so on.
The currently selected left mouse button mode is always displayed in the status bar next to the label "Current Mode". A number of things can change this mode (such as using the contextual menus, or clicking on buttons in the button bar). When you click or click and drag with the left mouse button in the view pane, the current mode is activated and an action is performed based on that mode. For example, if the current mode is "Orbit Scene", then clicking and dragging in the view pane will rotate the camera around the scene in a spherical fashion, as if you were orbitting it.
The right mouse button pops up contextual menus based on whatever you're pointing at. You press and hold it, select a menu item, and then release to active the item. Contextual menus are available for each pane, as well as for certain buttons, menu titles, and the contents selection tabs.
Most of the features of the Granny viewer are self-documenting. If you hold the mouse pointer over a button or other user interface element, it will display a line of explanatory text in the status bar next to the label "Highlight", and if you hold the mouse for a few seconds, it will also pop up the same text as a hovering tooltip.
The button bar is a hierachical menu system that contains all the commands the Granny viewer understands. At the root of the menu system is the main menu, which lists buttons that go to task-oriented or complete sub-menus. When in these sub-menus, there is always a "back" button at the top that brings you back to the main menu.
There are a number of different elements in the button bar. The most common type is just a button, which is a rectangular, text-labeled block with a small icon next to it. There are three types of buttons.
Action buttons have a diamond icon, and are drawn in blue. These buttons are one-click buttons - you click on them, and they perform an action. Examples would be "Zoom to Scene", "Back to Main Menu", and "Reset Orientation". Action buttons which indicate a menu change (such as "Back to Main Menu", or "Files") can also be short-circuited by holding down the right mouse button, which will pop up the menu as a contextual menu instead of switching the button bar to show it.
Toggle buttons have a square icon, and are drawn in red or green to indicate their state. When red, it means that the setting they represent is off. When green, it is on. Clicking on the toggle button switches the state from on to off, or from off to on, and so forth.
Mode buttons have a diagonal triangle icon, and are drawn in blue or orange to indicate their state. When blue, it means that the mode is not the current mode. When orange, it means that it is. Clicking on a mode button switches the current mode to that mode, at which point the button turns orange and the "Current Mode" indicator in the status bar will show the mode name.
In addition to the buttons, there are also menu section labels that describe the buttons that come below them. While these are usually present only for information purposes, occasionally a label will have a parenthetical phrase next to it. When this is the case, it means that the menu has multiple configurations. Clicking on the label with the left button will then cycle through the configurations, and holding the right mouse button will bring up a complete version of the menu.
Finally, there is one more item that may show up in the button bar, especially when you least expect it: the Granny logo! This is by far the most exciting part of the button bar, because not only do you get to see the Granny logo any time you run the viewer, but you can also click on the Granny logo to go directly to the RAD Game Tools web page, an operation available previously only by typing "http://www.radgametools.com" into your browser address bar!
The view pane is where you view models and animations. It has three different modes, each of which is accessible from the tabs lined across its top.
The first and most common mode is the "scene preview", which shows a 3D version of what a Granny file might look like if loaded in a typical engine (obviously, all engines render things differently, so it's only one possible interpretation). The manner in which meshes, models, textures, and animations are presented in this view are all configurable via the options in the appropriate button bar menus, as well as in the contextual menus off of the scene preview tab and the various listing tabs.
Since navigating a 3D scene is one of the most fundamental operations in a viewer, there are a number of shortcuts that you can use to do so in the view pane. First, if you are familiar with 3D Studio MAX, it's method of moving and zooming is duplicated in the viewer: dragging with the middle mouse button pressed will pan the view, and rolling the mousewheel will zoom in and out. If you are familiar with Maya, it's method is duplicated as well: ALT-left-drag will orbit the camera, ALT-middle-drag will pan, and ALT-left-and-middle-drag will zoom the camera.
There is also a way to move the camera entirely with the keyboard. The WSAD keys are configured to orbit the camera, and the R and F keys are configured to zoom the camera in and out.
The second mode in the view pane is the "texture inspection" mode. This mode is similar to the scene preview, but instead of drawing textures on the objects in the scene, it draws them as flattened rectangles instead. This allows you to inspect the textures directly, and see the UV coordinates unwrapped on to them (if you turn that feature on).
The third mode is the "detailed data view" mode. This mode shows the literal contents of the Granny file, as raw data, as it would appear if read in actual code. Across its top, there is a single line of text that shows the location in the data that is being displayed. Each structure is separated by a double semi-colon, and clicking on any previous structure will jump back to that data.
In the main part of the display, the detailed data view shows three columns. The first (very thin) column shows an index. This is for displaying which array elements you're viewing at any time. If the data you're viewing is not an array, then there will only be one index: 0.
The second column shows the type and name of a field. The type will be some Granny type, such as granny_real32 or granny_transform. The name will be whatever name that field has in the Granny SDK header file. Immediately adjacent to that name is the third column, which displays the value of the field.
If a field is a reference to some other structure or array, then the value area will be a clickable hotspot instead of a value printout. Clicking in this area will jump directly to that structure or array, so you can view it in more detail.
The listing pane does just that: it lists everything you currently have loaded. The tabs across its top select what you want to list, and the pane itself shows those items arranged vertically. If the item type you're listing has a specific associated visual, it will be shown in a small thumbnail along the left side of the pane. If it does not, then there will be no thumbnail.
When there is a thumbnail, clicking on the thumbnail will perform the most common operation on that item type. For example, if it is a texture, it will toggle the texture between its standard image and a calibration image. If it's a mesh, it will toggle whether or not it is shown. If it's an animation, it will transition to it.
Next to the thumbnail (or if there is no thumbnail, then across the entire pane) is the name of the item and some quick statistics about that item. Right-clicking on this data will bring up a context menu with the option "View in Detail". Selecting this option will display the itme in the detailed data view for closer inspection.
Launching the Viewer from the Command Line
By default, any command line arguments passed to the Granny viewer are loaded and their contents displayed. However, sometimes you may wish to restrict the way a file is loaded from the command line, such that only its model or only its animation data should be loaded, even if it contains both. To do this, you can use the "-animation" or "-model" switch. All files listed after the "-animation" switch will be loaded as animations only, and all files listed after the "-model" switch will be loaded as models only. You can use the switches in any order, and use either more than once, as appropriate.