perfly(3pf)
perfly - OpenGL Performer scene viewer
As shipped in IRIX 6.5.15. Added in IRIX 6.5.15.
NAME perfly - OpenGL Performer scene viewer SYNOPSIS perfly [ options ] file ... DESCRIPTION perfly is a sample application distributed with the OpenGL Performer high-performance graphics library. perfly is a powerful way to see graphics data: it's very fast, reads many different graphics file formats, and has interesting options for examining your dataset. If you are new to OpenGL Performer, the best way to start learning about it is to go for a test drive. The Performer-based sample application perfly is installed in the /usr/sbin directory. To run perfly, simply type "perfly" followed by a list of files that you want to see. For example: perfly esprit.flt There are quite a few models in the /usr/share/Performer/data directory that you may wish to explore. The formats supported by OpenGL Performer are listed toward the end of this reference page. perfly will by default start up with a trackball motion model. Type "man pfiXformer" for details on how to use the motion models: drive, fly, flight stick, and trackball. perfly is largely self-documenting. Run perfly with the command line option "-help" and a full list of features will be printed. Type "?" while running perfly to print a list of keyboard command sequences to the shell window. Perfly is used by many OpenGL Performer demos to view large databases, including the standard Performer Town demo. The Town is shipped in the fast-loading OpenGL Performer binary format (pfb). You can run the Town with perfly town.perfly. OPTIONS Perfly supports a large number of command line options. These options and the arguments accepted by each, are described below. Note: Characters such as the less-than and greater-than symbols in "<text>", the braces in "[text]", and so on are not meant to be typed on the command line itself; they represent regular expressions, optional arguments, or wildcard substitutions, and are for clarity of documentation. -A <string> Use <string> as the Welcome-screen text. Default is "Welcome to OpenGL Performer" -a <string> Use <string> as the text overlaid in the upper right corner of the perfly window (IRIX Only). Default is "OpenGL Performer" -B <num,...> -mapping of processes to procesors -b <r,g,b[,a]> Use the color specified by <r,g,b> (with optional alpha) as the background color when the EarthSky mode is set to "clear". Default is <0.07,0.11,0.18,1.0> -c <numChannels> Number of channels (side-by-side). Default is one per window. -C <a,b,c,...> Ordering of pipes in relation to channels, from left to right. ex: -C 2,0,1 makes pipe 0 display the center channel, whereas with -C 0,1,2 pipe 0 would display the leftmost. Default is in increasing number from left to right (0,1,2,..) -d Use 'drive' mode input model. See pfiXformer(3pf) for details. Default is 'trackball' mode. -D Lock down the DRAW process (if running in MP mode) on a particular CPU. Must have root permissions. Off by default. -e <h,p,r> -Initial view angles Set the initial view angle to the Euler angle specified by <heading,pitch,roll>. Default is <0,0,0> -E <string> Set the EarthSky (background) mode to <string>. Valid options are: clear : clear screen to the standard background color (default) sky : draw the sky polygons only; ground area is not cleared. skygrnd : draw both the sky and ground skyclear : draw the sky polygons and clear the ground area to the default background color. tag : Special fast 'tag' clear (only available on RealityEngine systems, where it is the default) -f Use 'fly' mode input model. See pfiXformer(3pf) for details. Default is 'trackball' mode. -F <path> Set the data-file search path to <path>. See pfFilePath(3pf) for details. Default is /usr/share/Performer/data or $PFPATH if set. -g <format> Set the display format of the graphical interface. Valid settings are: 0 : Turn GUI off 1 : Align the GUI vertically (default) 2 : Align the GUI horizontally -G Enable Gangdraw (PFCHAN_SWAPBUFFERS_SW) synchronization in multi-pipe mode. See pfChannel(3pf) for more information. Off by default. -h Print the command argument list, and exit. -i <count> Load <count> copies of each data file into the scene graph. Typically used in conjunction with -u or -X. Off by default. -I <count> Run perfly for <count> frames, then print performance statistics and exit. Off by default. -j <font_type> Set the font type of the welcome text (see -a). Valid settings are: 0 : 2D Textured Font 1 : 2D Outline Font 2 : 2D Filled Font 3 : 3D Filled & Extruded Font (Default) -J <font_name> Set the Font of the welcome text (see -a) to <font_name>. Currently, the only valid fonts are Mistr and Times-Elfin. Default is Mistr. -k <r,g,b[,a]> Set the color of outlines drawn when in 'scribed' mode to <r,g,b> with optional alpha. Default is <1.0,1.0,1.0> -K <count> Merge pfBillboards together, up to number <count>. See pfdCombineBillboards(3pf) for more information. Off by default. -l <style> -l <x,y,z,r,g,b> If arguments are of the format <style>, set the lighting style. Valid settings are: 0 : turn lighting off 1 : Illuminate the scene from the eyepoint (Default) 2 : Illuminate the scene from above If arguments are of the format <x,y,z,r,g,b>, then add a pfLightSource to the scene at position <x,y,z> with diffuse color <r,g,b>. Off by default. -L Free processesors, then lock Performer processes to a particular CPU. Must have root permission. Also see -D, -Z, and -B. Off by default. -m <mode> Override the default multiprocessing mode. Valid modes are: -1 : PFMP_DEFAULT : (Default) 0 : PFMP_APPCULLDRAW : All processes together 2 : PFMP_APP_CULLDRAW : App Separate, Cull & Draw together 4 : PFMP_APPCULL_DRAW : App & Cull together, Draw separate 6 : PFMP_APP_CULL_DRAW : App, Cull, and Draw all separate others: Other mode values may be 'OR'ed in; see pfMultiprocess(3pf) for more information. -M <mode> Override the default multi-pipe mode. Valid modes are: 0 : Force single-pipe mode 1 : Allow multi-pipe mode if detected (default) 2[,h=<netId>...][,s=<dpyName>...] : hyperpipe mode Hyperpipe mode arguments: <netId> - hyperpipe network id (see hyperpipeinfo(1)) <dpyName> - X display name for single pipe (including screen) Notes regarding hyperpipe: - hyperpipe rendering pipelines must preceed single pipelines - no netIds will configure no hyperpipes - no dpyNames will configure no single pipes - no netIds and dpyNames will configure all hyperpipes -n <level> Set the maximum notification level to <level>. Overrides $PFNFYLEVEL if set. Valid levels are: 0 : PFNFY_ALWAYS | Mandatory notifications only 1 : PFNFY_FATAL | Fatal errors 2 : PFNFY_WARN | Serious warnings 3 : PFNFY_NOTICE | General warnings (default) 4 : PFNFY_INFO | Progress or Status Information 5 : PFNFY_DEBUG | Verbose Debug information 6 : PFNFY_DEBUG_FP | Floating-point messages 6 : PFNFY_INTERNAL_DEBUG | Internal messages -N Assign non-degrading priorities to Performer processes. Off by default. -o <mode>,<value> Turn specified builder mode/value pair OFF. (see -O) -O <mode>,<value> Turn the specified builder mode/value pair ON. See the pfdBldrMode reference page for more information. Valid modes & values correspond to: 0 : PFDBLDR_MESH_ENABLE 1 : PFDBLDR_MESH_SHOW_TSTRIPS 2 : PFDBLDR_MESH_INDEXED 3 : PFDBLDR_MESH_MAX_TRIS 4 : PFDBLDR_MESH_RETESSELLATE 5 : PFDBLDR_MESH_LOCAL_LIGHTING 10 : PFDBLDR_AUTO_COLORS 0 : PFDBLDR_COLORS_PRESERVE + leave colors alone 1 : PFDBLDR_COLORS_MISSING - make missing colors 2 : PFDBLDR_COLORS_GENERATE - make all colors 3 : PFDBLDR_COLORS_DISCARD - toss existing colors 11 : PFDBLDR_AUTO_NORMALS 0 : PFDBLDR_NORMALS_PRESERVE - leave normals alone 1 : PFDBLDR_NORMALS_MISSING + make missing normals 2 : PFDBLDR_NORMALS_GENERATE - make all normals 3 : PFDBLDR_NORMALS_DISCARD - toss existing normals 12 : PFDBLDR_AUTO_TEXTURE 0 : PFDBLDR_TEXTURE_PRESERVE + leave texture coord alone 1 : PFDBLDR_TEXTURE_MISSING - make missing texture coord 2 : PFDBLDR_TEXTURE_GENERATE - make all texture coord 3 : PFDBLDR_TEXTURE_DISCARD - toss existing texture coord 13 : PFDBLDR_AUTO_ORIENT 0 : PFDBLDR_ORIENT_PRESERVE - leave normal and order alone 1 : PFDBLDR_ORIENT_NORMALS - make normal match vertex order 2 : PFDBLDR_ORIENT_VERTICES + make vertex order match normal 15 : PFDBLDR_AUTO_DISABLE_TCOORDS_BY_STATE 0 - dont remove tcoords if no texture specified 1 - remove tcoords if no texture specified 16 : PFDBLDR_AUTO_DISABLE_NCOORDS_BY_STATE 0 - dont remove ncoords if no material specified 1 - remove ncoords if no material specified 17 : PFDBLDR_AUTO_LIGHTING_STATE_BY_NCOORDS 0 - don't automatically set lighting enable based on presence of ncoords 1 - automatically set lighting enable based on presence of ncoords 18 : PFDBLDR_AUTO_LIGHTING_STATE_BY_MATERIALS 0 - dont automatically set lighting enable based on presence of material 1 - automatically set lighting enable based on presence of material 19 : PFDBLDR_AUTO_TEXTURE_STATE_BY_TEXTURES 0 - dont automatically set texture enable based on presence of tcoords 1 - automatically set texture enable based on presence of tcoords 20 : PFDBLDR_AUTO_TEXTURE_STATE_BY_TCOORDS 0 - dont automatically set texture enable based on presence of texture 1 - automatically set texture enable based on presence of texture 30 : PFDBLDR_BREAKUP 31 : PFDBLDR_BREAKUP_SIZE 32 : PFDBLDR_BREAKUP_BRANCH 33 : PFDBLDR_BREAKUP_STRIP_LENGTH 34 : PFDBLDR_SHARE_MASK 35 : PFDBLDR_ATTACH_NODE_NAMES 36 : PFDBLDR_DESTROY_DATA_UPON_BUILD 37 : PFDBLDR_PF12_STATE_COMPATIBLE 38 : PFDBLDR_BUILD_LIMIT -maximum number of tris/strip -p <x,y,z> Set the initial view position to <x,y,z>. Default is calculated based on database extent. Also see -e. -P <phase> Set the multi-process phase mode to <phase>. See pfPhase(3pf) for more information. Valid settings are: 0 : PFPHASE_FLOAT 1 : PFPHASE_LOCK 2 : PFPHASE_FREE_RUN (default) 3 : PFPHASE_LIMIT -q <0/1> Optimize graphics state by calculating and applying a global scene pfGeoState. See pfdMakeSharedScene(3pf) for more information. Default is 0 (off). -Q <0/1> Flatten the scene graph and prune empty SCS nodes. See pfdCleanTree(3pf) for more information. Default is 0 (off). -r <frameRate> Set the target frame rate in Hz to <frameRate>. Default is the monitor refresh rate. -R <0/1> Allow the pfdGeoBuilder to retesselate input geometry. Also see -o. 0 (off) by default. -s <LODscale> Set the global LOD scale to <LODscale>. See pfLOD(3pf) for more information. Off (1.0) by default. -S <0/1> Color-code each triangle strip with psychadelic pastels. Default is 0 (off). -t <0xVisual_id> Override the GLX Visual used by perfly to <0xVisual_id> (specified in hex). Can cause visual artifacts to occur if not chosen wisely. Default is internally calculated. -T <0/1> Compile data in geosets into GL display lists. This results in a performance optimization on most systems, at the cost of memory usage. On InfiniteReality systems, GL display lists are stored in the graphics pipeline. See pfGeoSet(3pf) for more information. Default is 1 (on). -u "Explode" or separate multiple input values by an internally calculated distance. Off by default. -v <format> Compile data in geosets into GL vertex arrays. See pfGeoSet(3pf) for more information. Valid formats are: 0 : Off (default) 1 : PFGS_PA_C4UBN3ST2FV3F - all attributes packed in arrays 2 : PFGS_PA_C4UBN3ST2F - all except verts packed in arrays -V <DVRmode> -V <DVRmode,xsize,ysize> Set DVR mode to <mode>. Only available on InfiniteReality systems. See pfPipeVideoChannel(3pf) for more information. Valid settings are: 0 : PFPVC_DVR_OFF 1 : PFPVC_DVR_MANUAL 2 : PFPVC_DVR_AUTOMATIC If arguments are given in the format <mode,xsize,ysize>, set the DVR mode to <mode> (as above) and the initial size to <xsize,ysize> -w <file>.out -w <file.ext> Upon exit, write scene graph to filename <file.ext> in the current working directory using the <ext> format store function, if it exists. If <ext> is 'out', pfPrint the scene graph in flat ASCII. -W <width,height> Set the window size to <width,height>. If height is omitted, uses the width value for both. Default is the screen size. -x <forkmode> Set the GLX input handling mode to <forkmode>. Valid modes are: 0 : synchronous X input handling is used. 1 : asynchronous X input handling is used. 2 : asynchronous X input allowing multi-pipe (default). -X <radius> "Explode" or separate multiple input values by the distance <radius>. 0 (off) by default. -y <ext,mode,value> Set the <mode> for file extention type <ext> to <value>. See pfdConverterVal(3pf) for more details. -Y <ext,alias> Substitute file extension <alias> for file extension <ext> when determining file type. See pfdLoadFile(3pf) for more details. -z <near,far> Set initial clipping plane ranges to <near,far>. -Z Attempt to lock CPUs without initially freeing them. Off by default. Perfly keyboard options Perfly supports several keyboard options. These are functions that can be invoked during simulation by typing the indicated key while the cursor is in the perfly window. Key Function ----- -------------- ESC Exit program ? Print help SPACE Stop moving F1KEY Toggle graphical user interface (GUI) b Toggle backface mode c Toggle collision detection C Change culling mode f Decrease the target frame rate F Increase the target frame rate g Toggle stats and stats graph G Print stats graph contents to stderr k Cycle through DVR modes (off,manual,auto) l Cycle through lighting modes (off, eye, sun) p Change frame phase r Reset positions s Toggle diagnostics display S Print stats graph contents to stderr t Toggle texturing on/off w Toggle draw mode between solid/wire W Cycle draw mode between all styles x Snapshot RGB screen image to file X Snapshot RGBA screen image to file z Show culling frustum Supported Database Formats Perfly, like all OpenGL Performer applications, is able to directly load 3D data in a large selection of popular formats and draw that data at high speed. All of the following file formats are understood by Perfly: 3ds AutoDesk 3DStudio binary data bin Minor SGI format used by powerflip bpoly Side Effects Software PRISMS binary byu Brigham Young University CAD/FEA data dwb Coryphaeus Software Designer's Workbench dxf AutoDesk AutoCAD ASCII format flt11 MultiGen public domain Flight v11 format flt14 MultiGen OpenFlight v14 format gds McDonnell-Douglas GDS things data gfo Minor SGI format (radiosity output) im Minor SGI format (OpenGL Performer example) irtp AAI/Graphicon Interactive Real-Time PHIGS iv SGI OpenInventor / Silicon Studio Keystone lsa Lightscape Technologies radiosity (ASCII) lsb Lightscape Technologies radiosity (binary) m University of Washington mesh data medit Medit Productions medit modeling tool nff Eric Haines' ray tracing test data format obj Wavefront Technologies data format phd Minor SGI format (polyhedra) pfa OpenGL Performer ASCII database format pfb OpenGL Performer fast loading BINARY database format (see the /usr/share/Performer/src/lib/libpfdb/libpfpfb/README for more information) poly Side Effects Software PRISMS ASCII data pts University of Washington point data ptu Minor SGI format (OpenGL Performer example) sgf US NAVY standard graphics format sgo Minor SGI format spf US NAVY simple polygon format sponge Sierpinski sponge 3D fractal generator star Yale University compact star chart data stla 3D Structures Stereolithography (ASCII) stlb 3D Structures Stereolithography (binary) sv Format of John Kichury's i3dm modeler tri University of Minnesota Geometry Center data unc University of North Carolina data While most loaders do in fact "load" data from files, scene graphs can also be generated procedurally. The sponge loader is an example of such automatic generation; it builds a model of the Menger (Sierpinski) sponge, without requiring an input file. To see the sponge run perfly specify the number of recursions (0, 1, 2, ...) as the filename. For example perfly 2.sponge InfiniteReality Demos With perfly, you can see many of the new features offered with the SGI InfiniteReality hardware. Dynamic Video Resolution (DVR): The InfiniteReality offers the ability to dynamically resize the output region of the framebuffer which can be used for load management. On a per-frame basis, current load can be evaluated and the output drawing area reduced to reduce load. The video hardware will scale up the output drawing area to match the full targeted size, with bilinear interpolation. This operation can be controlled manually by the application or in an parameterized automatic mode. Perfly can demonstrate these modes. % perfly -V 1,640,408 # Start up in manual DVR mode with initial size # as 640x480. The Up/down arrow keys will allow # you to adjust output region size. % perfly -V 2 # start up with automatic DVR Note that when DVR is enabled, the current output size of the video channel is displayed in the statistics status line (click the stats button in the GUI). Additionally, there will be an M or A displayed with the size to indicate Manual or Automatic DVR. For best results, AUTO DVR should be used in combination with the InfiniteReality graphics pipeline statistics. Graphics Pipeline Statistics: InfiniteReality offers graphics pipeline statistics for measuring load within the graphics pipeline. These statistics are not yet on by default in OpenGL Performer because only one application may successfully use them at a time in the initial IRIX 6.2 InfiniteReality release. However, graphics pipeline statistics are both much more accurate than timing measurements made on the CPU and are also less invasive. To turn these statistics on in perfly, click on the "Pipe" option in the statistics radio button in the GUI. The (GP=XXmsecs) in the status line indicates the graphics pipeline timing measurement. Other statistics modes (such as "Dft" for the full timing graph and "Gfx" for detailed drawing statistics" may than be selected and the pipeline statistics will stay enabled. Selection of "Fill" statistics or turning the statistics off will disable the graphics pipeline statistics. For more information, see the pfStats and pfFrameStats reference pages. Clip-Mapping for very large textures: OpenGL Performer and InfiniteReality together provide Clip- mapping for automatic viewing and paging of very large textures. For a demo, run: % perfly hl.ct The 'g' key toggles color-coded gridification of all clip textures in the scene. There is another program called clipfly that has many more clip texture related enhancements; see the clipfly man page for more information. NOTES When using DVR, perfly should always be run in full screen mode (do not use the -W option). Also, when DVR and the graphical user-interface are both enabled, the GUI must be redrawn whenever there is a video channel resize, or whenever the mouse is in the GUI. This is very expensive and a drop in framerate will be incurred. Only one application at a time may be using DVR. If a second application starts up and attempts to use DVR while the first is still executing, the second may terminate. See the pfPipeVideoChannel reference page for more information. Only one copy of perfly should be runing with graphics pipeline statistics ("Pipe") selected at a time. If multiple copies of perfly are running, de-select pipe stats in one before turning it on in another. Learning More Once you've seen OpenGL Performer in action, you will want to learn more about it. The OpenGL Performer Programming Guide and the OpenGL Performer Release Notes are the primary sources of information, but the a number of information sources are available to give you a good start in your learning process. The origin of this quest is the Performer man page. Just type "man performer" and just about everything you might want to know will be there or in one of the on-line resources listed there. SEE ALSO performer, clipfly, pfconv