HP Scalable Visualization Array Version 2.
© Copyright 2006, 2007 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice.
Table of Contents About This Document.........................................................................................................9 Intended Audience.................................................................................................................................9 Document Organization.........................................................................................................................9 Typographic Conventions.....................................................
Data Structures used by Frames......................................................................................................33 Sequencing Frame Functions...........................................................................................................34 Summary of Miscellaneous Functions..................................................................................................35 1 Session and System Functions...........................................................................
List of Figures 1-1 Relationships Among Library Entities..........................................................................................
List of Tables 1-1 1-2 2-1 2-2 2-3 2-4 2-5 2-6 2-7 2-8 2-9 2-10 2-11 2-12 2-13 B-1 B-2 B-3 B-4 B-5 Typical Call Sequence....................................................................................................................14 Sample Applications on Kit...........................................................................................................16 Properties of Library Parameter Types.........................................................................................
About This Document This document describes the Parallel Compositing Library. The document provides information on the library architecture and its functions. Intended Audience Application developers. Document Organization This document is organized as follows: Chapter 1 This chapter provides an overview of the Parallel Compositing Library (the Library), including its terminology and a typical calling sequence.
CAUTION IMPORTANT NOTE A caution calls attention to important information that if not understood or followed will result in data loss, data corruption, or damage to hardware or software. This alert provides essential information to explain a concept or to complete a task. A note contains additional information to emphasize or supplement important points of the main text.
1 Main Areas of the Parallel Compositing Library This chapter introduces you to the HP implementation of the Parallel Compositing Library (Library). It summarizes Library terminology. It also describes the sample applications that are available on the Library Kit to get you started. Introduction The Library is a set of related functions that make it possible for multiple graphics cards to collectively produce images. There are benefits to using multiple graphics cards rather than a single card.
Session A session is the Library entity that connects all the programs in an application. A session is identified by a property known as a sessionID. All programs that make up an application create a session by specifying the same sessionId. A program can be a part of only one session at a time. Host It is best to think of a host as a thread of execution. A host differs from a program in that a program can have more that one host. To contribute images to frames, a program must have at least one host.
Output An output is a subrectangle of a frame that a host needs to retrieve once the frame has been produced. A host declares at most one output that it needs to retrieve. The dimension and location of this output on the frame are stored in the context. Two different hosts can declare the same or different outputs. Result A result is a sub-rectangle of an output. The host can retrieve its output either as a whole or in pieces. Each rectangle of pixels retrieved from the output is called a result.
Figure 1-1 Relationships Among Library Entities system application 1 1 session 1 runs 0..n 1..n 0..n 0..n program host Key share 1..n 0..n context part owner 0..n client supplier framelet 0..1 entity 1 relates 1..n entity 2 output 1..n 1 frame 0..n result 1..n channel Order of Function Calls Applications that use the Library typically create a sequence of images. In Library terminology, each image is denoted as a frame.
Table 1-1 Typical Call Sequence (continued) Step Comment 3. Create a context. Either the pcContextCreate or pcContextCreateMaster function creates a session. Exactly one host calls pcContextCreateMaster to enumerate all the hosts that share the context. The remaining hosts call pcContextCreate when they are ready to share the context. 4. Set or get context properties. The Library needs to know certain properties of the frames that are produced, such as the overall size of the frame.
Sample Programs Available on Kit This section summarizes the samples available on the HP Library Kit. The sample programs are in the samples directory (/opt/paracomp/samples by default). The samples illustrate the call sequence detailed in Table 1-1. The sample code is well commented, including references to the steps in Table 1-1, for example, “5d: End of frame.” We recommend that you review the samples in order because each builds on concepts and features from previous samples.
ivp Sample The sample consists of one file, namely, ivp.c. It contains the program code with extensive comments. hello-depth Sample This sample consists of two files: • hello-depth.c This file contains the program code with extensive comments. • demo-depth.sh This file is a script to launch the sample on an SVA cluster. This sample shows how to do depth compositing using the Library. When run, the sample displays several cubes. Each node contributes one cube.
To run the hello-depth and hello-alpha samples, you must be logged into a node on which X is running. These examples display in a window on that X desktop and take advantage of one or more additional rendering nodes. Assume your SVA cluster has five nodes n[1-5]. You decide to use n5 as your desktop and use three render nodes to run either of the samples. Use a command such as sva_remote.sh, which allocates node n5, starts an X server, logs in to node n5, and runs the sample using the corresponding script.
guess what result might be available first. This is difficult to do when the size of the framelets is determined dynamically. The sample uses an additional class in the ../support directory for calculating the current frame rate. Here is how to control the program: Action How To Rotate the model. Hold MB1 and drag. Pan. Press the SHIFT key and drag with MB1. Zoom. Press the CTRL key and drag with MB1. Enable or disable the use of bounding boxes. Press the “b” key.
$ $ $ $ cd workingDir/samples/support make cd ../intermediate make The support directory contains a number of classes used by all samples. NOTE: You need at least two nodes to run any of the samples. You need an X desktop to run any of the sample programs. You can use the sva_remote.sh script to allocate such a desktop. The output of the sample displays on this X desktop. You can run each of the programs with a one or more additional of render nodes.
described in the HP SVA System Administration Guide.) Launch the sample using its launch script with a command such as the following: $ ./demo-multitile.sh -d tile2x2 • With Display nodes and render nodes To run the sample in this configuration, you need a Display Surface and some number of render nodes, for example, 4. Use a command such as the following: $ ./demo-multitile.sh -d tile2x2 -r 4 Coding Tips This section contains two kinds of tips: • • Common programming errors.
if(err != PC_NO_ERROR) reportError(err); /* Decide the pixel format to use with GL from the channel structure The code below is just intended to show how to handle the general case */ switch(channel.
Relating this back to GLUT, the use of GLUT by the master is very much as you would expect in a non-distributed application. On the other hand, the slaves use GLUT differently. The slaves are run in full screen mode. They declare a display function and set their idle function to post a re-display. Techniques to Maximize Performance • Best Pixel Format The best performance format for depth compositing for this release is PC_PF_BGR|PC_PF_Z32I.
int flag=1; setsockopt(sock, IPPROTO_TCP, TCP_NODELAY, (char*)&flag, sizeof(int)); • HP Remote Graphics Software (RGS) Impacts Performance If you are connected to a node using RGS and that node is using the Library to either render or display, RGS also needs to read back pixels from the graphics card’s framebuffer. This competes for resources with rendering and readback. Similarly, there is a performance loss if you point the X Display of a node using the Library to another machine over the network.
2 Overview of Functions and Properties This chapter summarizes the Library functions and any properties related to the functions. Parameter Types The following parameter types are used by functions in the Library: Table 2-1 Properties of Library Parameter Types PC Type Properties of the Type PCchannel A structure that describes a result. See Section for more information. PCcontext An opaque value representing an instance of a Library context.
Table 2-2 PCchannel Fields (continued) Result Property Description rowLength The number of elements between the start of row n and row n + 1 of the array. size The number of bytes between the start of adjacent array elements. width The width of the result in pixels. xOffset The x offset of the origin of the result within the output. yOffset The y offset of the origin of the result within the output. Table 2-3 describes the types of channels available.
Table 2-5 System Properties Property Qualifier Can be Set? Type Description PC_EXTENSIONS none no string The list of extension modules that are currently loaded. PC_LIB_VERSION none no integer States the version of the Library Specification supported by this version of the implementation. The value of the property is major-version*100 + minor-version. PC_LIBRARY_PATH none yes string The full directory path of the loaded Library. This includes the actual library file.
Table 2-6 Context Functions (continued) Function Description pcContextGetInteger Retrieves a context property as an integer. pcContextGetString Retrieves a context property as a string. pcContextSetInteger Sets an integer context property. pcContextSetString Sets a string context property. pcContextSync Synchronizes context changes for all hosts. Parallel compositing is based on the concept of multiple processes or threads creating parts of an image that are then combined and displayed.
Table 2-7 Summary of Context Properties Value1 Property global PC_COMPOSITE_TYPE integer Type Can Set On Context Create Can Description Change After Context Create yes no Specifies how the pixels from multiple hosts are composited. Specific values of this property include: PC_COMP_DEPTH The color of the pixel closest to the eye masks a more distant pixel. PC_COMP_ALPHA_SORT The color of the pixel is a blending of the colors of the 2 pixels.
Table 2-7 Summary of Context Properties (continued) Value1 Property Type Can Set On Context Create Can Description Change After Context Create The session ID for the current session as set by the pcSessionCreate function.
Table 2-7 Summary of Context Properties (continued) Value1 Property Type Can Set On Context Create Can Description Change After Context Create host-specific PC_HOSTID integer no no PC_HOSTNAME string no no PC_HOSTINDEX integer no no This property is the index for the current host. Each host has an index between 0 and (PC_NUM_HOSTS - 1). The index assigned to a host is its position in the array passed by the master to pcContextCreateMaster.
Table 2-7 Summary of Context Properties (continued) Value1 Property Type PC_WRITE_COUNT_EXT integer Can Set On Context Create Can Description Change After Context Create no no (Supported by more than one vendor.) 1 This property returns the number of bytes written by the local host to all other hosts since the last retrieval of this property. Retrieving the property resets the property to 0.
Table 2-10 Pixel Compositing Table Compositing Algorithms (Pixel Operator) Meaning PC_COMP_ALPHA_SORT The color of the pixel is a blending of the colors of the two pixels. The blending is dictated by the transparency (alpha value) of the two pixels. PC_COMP_DEPTH The color of the pixel closest to the eye masks a more distant pixel. Summary of Frame Functions This section summarizes context functions (there are no properties). Detailed syntax for the functions is in “Frame Functions” (page 55).
requests the channel be supplied in the output. When set to true (non-zero), the PC_OUTPUT_DEPTH context property requests the Library to provide the PC_CHANNEL_DEPTH for all outputs. A result is a sub-rectangle of an output. This means it is also represented by the same two-dimensional arrays. Although four entities are defined (frame, framelet, output, result), the frame functions only deal with two of these directly. Each host may present zero or more framelets to the Library to be composited.
The extension context parameters PC_VOLATILE_FRAMELET and PC_RETAIN_OUTPUT extend the lifetime of the frame for a requested number of frames. See the description of pcFrameAddFramelet for more details. Summary of Miscellaneous Functions This section summarizes miscellaneous functions (there are no additional properties). Detailed syntax for the functions is in “Miscellaneous Functions” (page 69). Table 2-13 lists and briefly describes the miscellaneous functions.
Session and System Functions This reference section provides detailed syntax on session and system functions.
pcSessionCreate(3) NAME pcSessionCreate -- Creates a parallel compositing session. Synopsis PCerr pcSessionCreate( PCid sessionId ); Parameters sessionId An unsigned integer that acts as a unique identifier of the session. All programs that are a part of an application must call this function with the same identifier. If there are multiple sessions that are sharing a network at a given time, each session must have a different sessionId. Returns This function returns PC_NO_ERROR on successful completion.
pcSessionDestroy(3) NAME pcSessionDestroy -- Destroys a Library session. Synopsis PCerr pcSessionDestroy(void); Parameters None. Returns This function returns PC_NO_ERROR on successful completion. Description pcSessionDestroy ends the active Library session. It destroys all the active contexts that are a part of the session before returning.
pcSystemFinalize(3) NAME pcSystemFinalize -- Un-initializes the Library for a program. Synopsis PCerr pcSystemFinalize(void); Parameters None. Returns This function returns PC_NO_ERROR on successful completion. Description This function unloads the Library so it can no longer be used by a program. This is an optional call. If pcSystemFinalize is not called, the Library remains loaded until the program exits.
pcSystemGetInteger(3) NAME pcSystemGetInteger -- Retrieves a system property as an integer. Synopsis PCerr pcSystemGetInteger( PCenum property, PCint qualifier, PCint* value ); Parameters property The property to retrieve. The names of the supported properties are listed in Table 2-5 in the Parallel Compositing Library Reference Guide. qualifier The qualifier of the property to retrieve. For those properties that do not require a qualifier, this parameter is ignored.
pcSystemGetString(3) NAME pcSystemGetString -- Retrieves a system property as a string. Synopsis PCerr pcSystemGetString( PCenum property, PCint qualifier, PCstring* value ); Parameters property The property to retrieve. The names of the supported properties are listed in Table 2-5 in the Parallel Compositing Library Reference Guide. qualifier The qualifier of the property to retrieve. For those properties that do not require a qualifier, this parameter is ignored.
pcSystemInitialize(3) NAME pcSystemInitialize -- Initializes the Library for a program. Synopsis PCerr pcSystemInitialize( const PCstring searchPath ); Parameters searchPath A pointer to a string that specifies an additional directory to search for the Library shared libraries before looking in the standard system directories. Returns This function returns PC_NO_ERROR on successful completion. Description This function initializes a program's use of the Library.
Context Functions This reference section provides detailed syntax on Context functions.
pcContextCreate(3) NAME pcContextCreate -- Creates a context as a slave. Synopsis PCerr pcContextCreate( PCid netId, PCstring thisHost, PCcontext *ctx ); Parameters netId thisHost The ID of the network transport layer for this context. It must match the value of the PC_NETWORK_ID property passed to pcContextCreateMaster. To use the default network, specify PC_ID_DEFAULT (the first transport layer).
pcContextCreateMaster(3) NAME pcContextCreateMaster -- Creates a context as the master. Synopsis PCerr pcContextCreateMaster( const PCint *properties, PCstring *hosts, PCstring thisHost, PCcontext *ctx ); Parameters properties An array of initial properties for the context. The array is a series of value pairs as follows: • The first element of the pair is the name of a property listed in Table 2-7 in the Parallel Compositing Library Reference Guide.
pcContextDestroy(3) NAME pcContextDestroy -- Destroys an existing context. Synopsis PCerr pcContextDestroy( PCcontext ctx ); Parameters ctx The context to destroy. Returns This function returns PC_NO_ERROR on successful completion. Description This function destroys an existing context. All hosts that originally created the context must call this function. The function blocks until all hosts have called it. This function cannot be called between pcFrameBegin and pcFrameEnd calls on the same context.
pcContextGetInteger(3) NAME pcContextGetInteger -- Retrieves a context property as an integer. Synopsis PCerr pcContextGetInteger( PCcontext ctx, PCenum property, PCint hostIndex, PCint* value ); Parameters ctx property The context whose properties are to be retrieved. The property to retrieve. The names of the supported properties are listed in Table 2-7 in the Parallel Compositing Library Reference Guide.
pcContextGetString(3) NAME pcContextGetString -- Retrieves a context property as a string. Synopsis PCerr pcContextGetString( PCcontext ctx, PCenum property, PCint hostIndex, PCstring* value ); Parameters ctx property The context whose properties are to be retrieved. The property to retrieve. The names of the supported properties are listed in Table 2-7 in the Parallel Compositing Library Reference Guide.
pcContextSetInteger(3) NAME pcContextSetInteger -- Sets an integer context property. Synopsis PCerr pcContextSetInteger( PCcontext ctx, PCenum property, PCint hostIndex, PCint value ); Parameters ctx property The context whose properties are to be set. The property to set. The names of the supported properties are listed in Table 2-7 in the Parallel Compositing Library Reference Guide and denoted as “Can Change After Context Create.
pcContextSetString(3) NAME pcContextSetString -- Sets a string context property. Synopsis PCerr pcContextSetString( PCcontext ctx, PCenum property, PCint hostIndex, PCstring value ); Parameters ctx property The context whose properties are to be set. The property to set. The names of the supported properties are listed in Table 2-7 in the Parallel Compositing Library Reference Guide and denoted as “Can Change After Context Create.
pcContextSync(3) NAME pcContextSync -- Synchronizes context changes for all hosts. Synopsis PCerr pcContextSync( PCcontext ctx ); Parameters ctx The context whose properties are to be synchronized. Returns This function returns PC_NO_ERROR on successful completion. Description The Library supports any of the hosts making changes to the values of Context Properties.
Frame Functions 55
pcFrameAddFramelet(3) NAME pcFrameAddFramelet -- Adds a framelet to the frame. Synopsis PCerr pcFrameAddFramelet( PCcontext ctx, PCid frameId, PCvoidp color, PCvoidp depth ); Parameters ctx frameId color depth The context for this frame. The unique ID generated for this frame by pcFrameBegin. A pointer to the buffer containing the color pixels for this framelet. A pointer to the buffer containing the depth data for the pixels of this framelet.
NOTE: The HP Library supports only the default value of 0. The PC_VOLATILE_FRAMELET_LIMIT system property specifies the maximum value of this property. PC_VOLATILE_FRAMELET 0 (default): This value requires the Library to extract any information it needs from the framelet before returning to the caller. Note that this is the only value supported by the HP Library. 1: The library can continue to extract information and modify the framelet until the next pcFrameBegin caller.
pcFrameAddGLFrameletEXT(3) NAME pcFrameAddGLFrameletEXT -- Adds current pixels on the graphics card as a framelet. Synopsis PCerr pcFrameAddGLFrameletEXT( PCcontext ctx, PCid frameId, PCint xOffset, PCint yOffset ); Parameters ctx frameId xOffset yOffset The context for this frame. The unique ID generated for this frame by pcFrameBegin. Horizontal offset in the extracted image on this graphics card to use as the origin. Vertical offset in the extracted image on this graphics card to use as the origin.
pcFrameBegin(3) NAME pcFrameBegin -- Begins a new frame. Synopsis PCerr pcFrameBegin( PCcontext ctx, PCid* frameId, PCuint numFramelets, PCuint* xOffset, PCuint* yOffset, PCuint* width, PCuint* height, PCuint* order ); Parameters ctx frameId numFramelets xOffset yOffset width height order The context for this frame. A unique ID generated by the Library for this frame. This ID is used on subsequent calls to the Library to identify the call as being for this frame.
The numFramelets parameter states the number of framelets that are added by this host before it calls pcFrameEnd. The remaining parameters describe the properties of each framelet that are added. The first element in each array gives the properties of the first framelet that is added by pcFrameAddFramlet; the second element in each array gives the properties of the second framelet to be added, and so on.
pcFrameEnd(3) NAME pcFrameEnd -- Ends the frame. Synopsis PCerr pcFrameEnd( PCcontext ctx, PCid frameId ); Parameters ctx frameId The context for this frame. The unique ID generated for this frame by pcFrameBegin. Returns This function returns PC_NO_ERROR on successful completion. Description This function marks the end of adding framelets to the frame. It corresponds to the End the frame Step in Table 1-1 (page 14) of the Parallel Compositing Reference Guide.
pcFrameResultChannel(3) NAME pcFrameResultChannel -- Retrieves resultant pixels for the frame. Synopsis PCerr pcFrameResultChannel( PCcontext ctx, PCid frameId, PCuint xOffset, PCuint yOffset, PCuint width, PCuint height, PCuint channelType, PCchannel channel ); Parameters ctx frameId xOffset yOffset width height channelType channel The context for this frame. The unique ID generated for this frame by pcFrameBegin. The x offset in pixels from the origin of the output.
rowSpan = channel.size * channel.rowLength + modulo( channel.size * channel.rowLength, channel.alignment ) address of (x,y) = channel.address + y * rowSpan + x * channel.size A host may call pcFrameResultChannel one or more times, provided the PC_OUTPUT_WIDTH and PC_OUTPUT_HEIGHT context properties are set to non-zero values. Each call may request the same or a different channel. Setting either PC_OUTPUT_WIDTH or PC_OUTPUT_HEIGHT to 0 indicates that the host will not request a result.
pcFrameResultQuery(3) NAME pcFrameResultQuery -- Tests if a frame result is available. Synopsis PCerr pcFrameResultQuery( PCcontext ctx, PCid frameId, PCuint xOffset, PCuint yOffset, PCuint width, PCuint height ); Parameters ctx frameId xOffset yOffset width height The context for this frame. The unique ID generated for this frame by pcFrameBegin. The x offset in pixels from the origin of the output. The y offset in pixels from the origin of the output. The width of the result in pixels.
pcFrameWaitOutputHP(3) NAME pcFrameWaitOutputHP -- Retrieves available output. Synopsis PCerr pcFrameWaitOutputHP( PCcontext ctx, PCid frameId, PCresult result ); Parameters ctx frameId result The context for this frame. The unique ID generated for this frame by pcFrameBegin. A PCresult that is initialized by this function. Returns This function returns PC_NO_ERROR on successful completion.
section of pcFrameResultChannel function in the Parallel Compositing Library Reference Guide for further details. This function is only available from the HP Library.
pcResultDestroyHP(3) NAME pcResultDestroyHP -- Resets a PCresult. Synopsis PCerr pcResultDestroyHP( PCresult result ); Parameters result A PCresult. Returns This function returns PC_NO_ERROR on successful completion. Description Calling this function resets a PCresult so that it no longer references a result. This is needed because a result continues to return valid properties for the number of frames specified by the PC_RETAIN_OUTPUT context property.
pcResultGetChannelHP(3) NAME pcResultGetChannelHP -- Gets a channel of a result. Synopsis PCerr pcResultGetChannelHP( PCresult result, PCuint channelType, PCchannel* channel ); Parameters result channelType channel A PCresult. The channel to return. A PCchannel initialized for accessing the channel specified by this function. Returns This function returns PC_NO_ERROR on successful completion.
Miscellaneous Functions 69
pcGetErrorString(3) NAME pcGetErrorString -- Gets a text description of a PCerr. Synopsis PCstring pcGetErrorString( PCerr error ); Parameters error A Library error code. Returns A string describing the Library error code passed as the first parameter. If the parameter error is not a Library error code, “Unknown error” is returned. The program must not free the storage holding the string.
pcGetProcAddress(3) NAME pcGetProcAddress -- Gets the address of an extension function. Synopsis PCvoidp pcGetProcAddress( PCstring funcName ); Parameters funcName The name of an extension entry point. Returns NULL if the function is not implemented in this version of the Library; otherwise, the address of the function. Description This function returns a pointer to a function that is defined by an extension to the Library.
pcQueryExtension(3) NAME pcQueryExtension -- Queries if an extension is present. Synopsis PCint pcQueryExtension( PCstring extensionName ); Parameters extensionName The name of an extension entry point. Returns True (non-zero) if the extension named by the extensionName parameter is present in the implementation; otherwise false (0). Description This function tests if an extension is available in the current Library implementation.
A Library Versions The definition of the Parallel Library specification changes over time. Appendix B explains how new features may eventually be adopted as standard features. Several system properties provide the following version information: • The version of the specification to which the current Library implementation conforms. • Any version attached by the vendor to the implementation to reflect different releases.
B Functions and Properties of Extensions Summary of Functions and Properties of Extensions This section summarizes Library extensions, along with their functions and properties. Detailed syntax for the functions is in the appropriate Reference sections. All the extended functions and properties listed in this Appendix are in the HP Library. Table B-1 lists the available extensions and the functions and properties for each extension.
To distinguish extensions from core library features, the following naming conventions exist: • A unique extension name of the form, PC__ is associated with each extension. If more than one vendor supports the extension, is EXT. If a single vendor supports the extension, designates that vendor. For example: — PC_EXT_io_count is an extension supported by more than one vendor. — PC_HP_frame_output is an extension supported by HP.
Table B-3 briefly describes the available functions for this extension. See “Frame Functions” (page 55) for detailed syntax of this function. There are no additional properties for this extension. Table B-3 Summary of PC_EXT_cur_gfx_ctx Functions Function Description pcFrameAddGLFrameletEXT Adds current pixels on graphics card. PC_HP_frame_output Extension The PC_HP_frame_output extension reduces the latency of extracting pixels and depth data from an output.
Index A Application entity, 11 B Benefits of Library, 11 C Call ordering, 14 Channel types, 26 Channels needed for pixel operators, 33 Color channel, 13 Context entity, 12 Context properties, 28 D Data structure used by frames, 33 Depth channel, 13 E Entities relationships among, 13 Entities of the Library, 11 Extensions functions and properties, 75 F Frame data structure, 33 Frame entity, 12 Framelet entity, 12 Function calls ordering of, 14 H Host entity, 12 Host identifier, 28 hostID, 12, 28 hostNa
V Version of Library, 73 80 Index
