|
|
RxPipelineNodePS2ManagerInstanceCallBack is the callback to be called, for the owning PS2Manager pipeline node, after standard instancing has occurred. Within this callback, code may instance data for user clusters and setup other DMA data (such as a second texture to upload for use in environment mapping). This callback will receive pointers to cluster data for all clusters (requested through RxPipelineNodePS2ManagerGenerateCluster) which have CL_ATTRIB_READ or CL_ATTRIB_WRITE attributes. This is guaranteed to include, in addition to user-generated clusters, the RxPS2Mesh cluster (placed first in the array) and the RxPS2DMASessionRecord cluster (placed second in the array). Even if there are no other user-generated clusters with CL_ATTRIB_READ or CL_ATTRIB_WRITE attributes, the callback is still called. If the callback returns FALSE then the current mesh will not be rendered. The rest of the object's meshes will be processed as normal.
|
|
|
RxPipelineNodePS2ManagerPostObjectCallBack is the callback to be called, for the owning PS2Manager pipeline node, after all meshes in an object have been processed (remember that PS2Manager is used in object pipelines, not material pipelines), such that cleanup may be performed at the end of the object's pipeline execution (without having to interfere with the object's render callback). This callback will receive a pointer to the data of the RxPS2DMASessionRecord cluster. The callback should return FALSE to indicate an error.
|
|
|
RxWorldApplyLightFunc RxWorldApplyLightFunc is a call back function for lighting See RxPipelineNodePS2AllObjectSetupCallBack or RxPipelineNodePS2ManagerSetLighting for details.
|
|
|
RxNodeDefinitionGetPS2Manager returns a pointer to the "PS2ManagerWorldSector.csl", "PS2ManagerAtomic.csl" or "PS2ManagerIm3D.csl" node definition - these being to render, respectively, world sectors, atomics or the geometry submitted through calls to RwIm3D render functions. This node does everything required to render an object, with minor restrictions. It performs the function of the PS2ObjAllInOne.csl, PS2MatInstance.csl and PS2MatBridge.csl nodes combined. This node will not pass packets on to subsequent nodes in the pipeline nor will accept them from previous nodes - it was designed to be the only node in a pipeline, for maximum speed (the PVSWorldSector.csl node, if placed before it, will still work since it doesn't use packets). PS2Manager.csl will also ignore material pipelines, so that all meshes in objects will be rendered in the same style (that defined by the object pipeline). This node will be made more customizable in future releases so that it will be the only node (bar PVSWorldSector.csl) that you need on PlayStation 2.
|
|
|
RxNodeDefinitionGetPS2MatBridge returns a pointer to a node to bridge the bottom of a main CPU based material pipeline to a set of VU1 based pipelines. This node has an API for use both during and after pipeline construction. First, the appropriate chunk of VU1 code (see RxPipelineNodePS2MatBridgeSetVU1CodeArray) is uploaded (unless it is already on VU1), then renderstate is specified (including management of the texture cache, with respect to this mesh's material's texture). Finally, material color and surface properties are uploaded and the transfer of mesh geometry data is kicked off (or queued, rather, since older DMA transfers will still be executing). This node destroys packets after it has initiated dispatch to the VU1 (this may change but it is done this way currently to avoid mesh data being modified before its DMA transfer has completed). The node has no outputs The input requirements of this node:
|
|
|
RxNodeDefinitionGetPS2MatInstance returns a pointer to a node to "instance" a mesh. Note that this node has a construction time API. On the PlayStation 2, instancing of data is performed in the material pipeline on a per-mesh basis. This is because different material pipelines can require data to be instanced into a different format, depending on what the nodes in the pipeline and VU1 code (associated with the pipeline) require. This node can instance meshes containing any RwPrimitiveType, indexed or unindexed. For every data type required to be "broken out" (vertex positions, normals, prelight colors, UVs or user-defined data types), a cluster is created (see the documentation for RxPipelineNodePS2MatInstanceGenerateCluster - briefly, it is requested by the application at pipeline construction time that these data types are exposed in clusters to the subsequent nodes in the CPU-side material pipeline. The default is for data to be invisible, since the optimal format for instanced data is a complex, packed DMA-readable structure which is not suitable for referencing as cluster data). The node checks which parts of the mesh's data need reinstancing. It instances this (from the source world sector or atomic) into the DMA-readable structure in a RwResEntry which is referenced by the RxClPS2Mesh cluster. Every data type exposed by a cluster is instanced into a suitable form (again see the documentation for RxPipelineNodePS2MatInstanceGenerateCluster). Depending on how much has changed in the mesh (from modified UVs to a completely rebuilt mesh) only a subset of the data may be reinstanced or (more costly) the entire RwResEntry may be thrown away and the DMA structure rebuilt from scratch. The node has one output, through which the instanced mesh passes. The input requirements of this node: RxClPS2DMASessionRecord - required RxClPS2Mesh - required The characteristics of this node's first output: RxClPS2DMASessionRecord - valid RxClPS2Mesh - valid
|
|
|
RxNodeDefinitionGetPS2ObjAllInOne returns a pointer to the "PS2ObjWorldSectorAllInOne.csl" or "PS2ObjAtomicAllInOne.csl" node definition - these being to generate a packet for each mesh in, respectively, world sectors or atomics. RxNodeDefinitionGetPS2ObjAllInOne has one parameter which you use to choose whether you want a node to handle world sectors or atomics. On the PlayStation 2, instancing of data is performed in the material pipeline on a per-mesh basis. This is because different material pipelines can require data to be instanced into a different format, depending on what the VU1 code (associated with the pipeline) requires. This means that PS2*ObjAllInOne.csl is not the equivalent of AtomicInstance.csl or WorldSectorInstance.csl which form the default generic atomic and world sector object pipelines. Instead, it does some per-object setup and then generates a packet per mesh and dispatches them to their associated material pipelines. PS2*ObjAllInOne.csl determines if the object's bounding volume crosses the frustum (this is the large PlayStation 2 overdraw frustum) and selects a clipping transform if so or a non-clipping transform if not. It also checks to see if the object is made of trilists or tristrips and selects a trilist transform or a tristrip transform respectively. The selected transform is specified in a PS2DMASessionRecord structure and an inFrustum state is stored there also. The node then calculates the object-to-camera matrix and finds all the lights which affect the object. These pieces of information are added to a VU1 packet and uploaded (just once since they are per-object not per-mesh). Next, a packet is generated for every mesh, containing a reference to the RxPS2DMASessionRecord structure in a RxClPS2DMASessionRecord cluster. An RxClPS2Mesh cluster containing a RxPS2Mesh structure is also created which contains a reference to the RpMesh and also the RwResEntry used for caching the instanced data for each mesh - plugin data attached to the world sector or atomic contains a list of references to these RwResEntry. The node will output each packet to the pipeline referenced in its mesh's associated material. There is an alternative, potentially more efficient mode of execution (where all meshes get passed down this pipeline to 'inlined' material rendering nodes), which is described in detail in the docs for RxPipelineNodePS2ObjAllInOneSetGrouping.
|
|
||||||||||||||||||||
|
RxPipelineNodePS2ManagerApplyLight is the default RxWorldApplyLightFunc which may be called, for each light affecting an object, to get lighting information uploaded to VU1 by a PS2Manager-based object pipeline. Lighting is performed in object-space (to avoid transforming object normals), hence this function requires a matrix to transform lights from world-space into object-space (i.e. it should be the inverse of the object's LTM matrix). This matrix must be orthogonal, though it need not be normalized. Both the scaling factor (1.0 if the matrix IS normalized) and its reciprocal need to be passed to this function so that the light's radius and direction vector may be scaled and renormalized after transform. Note that the matrix and scaling values need only be supplied for the first light affecting an object - they are only uploaded once.
|
|
||||||||||||||||
|
RxPipelineNodePS2ManagerGenerateCluster is used to force this node to generate clusters. It should be called with a pointer to this node and each of the RxClPS2* clusters required. This function must be called before the pipeline containing this node is unlocked because that is when cluster attributes are finalized. These are the PlayStation 2-specific clusters you can request for this node (see also RxPS2ClusterType):
Currently, PS2Manager.csl is in a nascent form but in its final incarnation, PS2Manager.csl will be all that you will need on PlayStation 2 and will allow instancing of custom data and customizable per-object, per-mesh and per-vertex data. The recently-added RxPipelineNodePS2ManagerSetInstanceCallBack should provide as much flexibility as with pipelines constructed from the separated PS2ObjAllInOne.csl, PS2MatInstance.csl and PS2MatBridge.csl nodes with additional inserted user nodes. The exception is that PS2Manager.csl ignores material pipelines so that all meshes within an object are rendered in the same style (that defined by the object pipeline). You must request at least one cluster for the pipeline to function. This function should be called before unlocking the pipeline containing this node.
|
|
|
RxPipelineNodePS2ManagerGetVU1CodeArray is a node API function which retrieves an array of pointers to the VU code fragments currently to be used by this pipeline. It mirrors RxPipelineNodePS2ManagerSetVU1CodeArray This function must be called after unlocking the pipeline containing the PS2Manager.csl node.
|
|
||||||||||||
|
||||||||||||
|
RxPipelineNodePS2ManagerNoTexture is a post construction time API which permits preventing the manager node from uploading any texture information. By default, the manager node will upload the raster for each mesh's texture to video memory, just before the geometry of that mesh is processed by VU1. It will also set up the appropriate filtering and addressing modes for the texture. This API function can be used to prevent this from happening. This is useful if a user-supplied instance callback (see RxPipelineNodePS2ManagerSetInstanceCallBack) is able to set up textures itself more efficiently than can the manager node (given that it is written based on knowledge of the current application), if the instance callback needs to choose the texture to upload from somewhere other than the object's materials, etc. This function must be called after unlocking the pipeline containing the PS2Manager.csl node.
|
|
||||||||||||
|
RxPipelineNodePS2ManagerSetInstanceCallBack is used to register a callback to instance data or set up additional DMA data. The registered callback will be called after standard instancing has occurred - standard instancing being that done by PS2Manager. User cluster or clusters with CL_ATTRIB_DONT_FILL or CL_ATTRIB_PLACEHOLDER attributes will not be instanced by PS2Manager. The instance callback will receive an array of pointers to cluster data for all clusters which have CL_ATTRIB_READ or CL_ATTRIB_WRITE specified (the clusters that can be filled in by user CPU-side code). The first pointer will always be to the RxPS2Mesh cluster and the second to the RxPS2DMASessionRecord cluster. There need not be any further (CL_ATTRIB_READ or CL_ATTRIB_WRITE) clusters for the callback to be called (a plug-in may, for example, only want to upload a texture or some static data). The default instancing code (called for all standard, non-read-or-write clusters) can instance from meshes containing any RwPrimitiveType, indexed or unindexed. User-supplied callbacks, however, need only handle meshes of the types required by the user. This function should be called after unlocking the pipeline containing this node.
|
|
||||||||||||
|
RxPipelineNodePS2ManagerSetLighting allows you to overload PS2Manager.csl with your own lighting system. The Lighting function you pass must have the following format: void RxWorldLightingCallBack *(RwInt32 objectType, void *object) This function should be called after unlocking the pipeline containing this node.
|
|
||||||||||||||||
|
RxPipelineNodePS2ManagerSetPointListVUBufferSize is used to set the maximum number of vertices for pointlists that may be passed to the VU code section of the pipe containing this node. The stride (in quad words) of the input buffer in vector memory is also set by this function. This function should be called instead of RxPipelineNodePS2ManagerSetVUBufferSizes, they should not both be called. Pipelines set up with this function will only be able to handle pointlist objects, not triangle- or line-based objects. For pipelines feeding user supplied VU code, the values to pass to this function may be obtained from the pipeline specific header file created by processing stddata.i. Note that for a pointlist pipeline, the first half of the VU1 code array should be used - i.e the TRANSTRI slots are reused. (see RxPipelineNodePS2ManagerSetVU1CodeArray) This function should be called before unlocking the pipeline containing this node.
|
|
||||||||||||
|
RxPipelineNodePS2ManagerSetPostObjectCallBack is used to register a callback to perform post-object cleanup. The registered callback will be called, for the owning PS2Manager pipeline node, after all meshes in an object have been processed (remember that PS2Manager is used in object pipelines, not material pipelines), such that cleanup may be performed at the end of the object's pipeline execution (without having to interfere with the object's render callback). This callback will receive a pointer to the data of the RxPS2DMASessionRecord cluster. This function should be called after unlocking the pipeline containing this node.
|
|
||||||||||||
|
RxPipelineNodePS2ManagerSetVIFOffset is used to set the VIF offset that is used when processing multiple batches of data. If this function is not called, a value suitable for the default code fragments and static data allocations will be used. For user provided VU1 code, this value can be obtained from the pipeline specific headerfile generated by processing stddata.i This function must be called after unlocking the pipeline containing the PS2Manager.csl node.
|
|
||||||||||||
|
RxPipelineNodePS2ManagerSetVU1CodeArray is a node API function which permits setting of the VU code fragments to be used by this pipeline. The bridge node connects its main CPU based pipeline to up to 16 different VU1 based pipelines. These are provided as an array of 16 pointers to callable DMA chain mode packets that will upload code to location 0 onward on VU1. The array is indexed using the TRANS* bit values stored in the RxClPS2DMASessionRecord cluster (there are 4 such toggles, hence 16 combinations - note that user created code fragments may be used and TRANS* values set by a user node if the default clip/list/iso/fog values set by PS2WorldSectorObjAllInOne.csl/ PS2AtomicObjAllInOne.csl are not appropriate).
NOTE: For a pointlist pipeline, the first half of the code array should be used - i.e the TRANSTRI slots are reused. (see RxPipelineNodePS2ManagerSetPointListVUBufferSize) This function must be called after unlocking the pipeline containing the PS2Manager.csl node.
|
|
||||||||||||||||||||
|
RxPipelineNodePS2ManagerSetVUBufferSizes is used to set the maximum number of triangles (for trilists) and vertices (for tristrips) that may be passed to the VU code section of the pipe containing this node. The stride (in quad words) of the input buffer in vector memory is also set by this function. If this function is not called the defaults required by the standard transforms will be used. For pipelines feeding user supplied VU code, these vaules may be obtained from the pipeline specific header file created by processing stddata.i This function should be called before unlocking the pipeline containing this node.
|
|
|
RxPipelineNodePS2MatBridgeGetVU1CodeArray is a post construction time API function which retrieves an array of pointers to the VU code fragments currently to be used by this pipeline. It mirrors RxPipelineNodePS2MatBridgeSetVU1CodeArray
|
|
||||||||||||
|
RxPipelineNodePS2MatBridgeNoTexture is a post construction time API which permits preventing the bridge node from uploading any texture information. By default, the bridge node will upload the raster for each mesh's texture to video memory, just before the geometry of that mesh is processed by VU1. It will also set up the appropriate filtering and addressing modes for the texture. This API function can be used to prevent this from happening. This is useful if a custom user node (inserted in the pipeline before the bridge node) is able to set up textures itself more efficiently than can the bridge node (given that it is written based on knowledge of the current application), if the custom node needs to choose the texture to upload from somewhere other than the object's materials, etc. This function must be called after unlocking the pipeline containing the bridge node.
|
|
||||||||||||
|
RxPipelineNodePS2MatBridgeSetVIFOffset
is used to set the VIF offset that is used when processing multiple
batches of data. If this function is not called, a value suitable
for the default code fragments and static data allocations will be
used. For user provided VU1 code, this value can be obtained from
the pipeline specific header file generated by processing
|
|
||||||||||||
|
RxPipelineNodePS2MatBridgeSetVU1CodeArray is a post construction time API function which permits setting of the VU code fragments to be used by this pipeline. The bridge node connects its main CPU based pipeline to up to 16 different VU1 based pipelines. These are provided as an array of 16 pointers to callable DMA chain mode packets that will upload code to location 0 onward on VU1. The array is indexed using the TRANS* bit values stored in the RxClPS2DMASessionRecord cluster (there are 4 such toggles, hence 16 combinations - note that user created code fragments may be used and TRANS* values set by a user node if the default clip/list/iso/fog values set by PS2WorldSectorObjAllInOne.csl/ PS2AtomicObjAllInOne.csl are not appropriate).
NOTE: For a pointlist pipeline, the first half of the code array should be used - i.e the TRANSTRI slots are reused. (see RxPipelineNodePS2MatInstanceSetPointListVUBufferSize)
|
|
||||||||||||||||
|
RxPipelineNodePS2MatInstanceGenerateCluster is used to force this node to generate clusters. It should be called with a pointer to this node and each of the RxClPS2* clusters required. This function must be called before the pipeline containing this node is unlocked because that is when cluster attributes are finalized. These are the PlayStation 2-specific clusters you can request for this node (see also RxPS2ClusterType):
The format attributes of the first four of the above PlayStation 2-specific clusters are fixed and you cannot change them, however the instance flags can be changed. The user-defined clusters can have any attributes you please. Since these cluster definitions are static globals and provided really as examples, it is suggested that you create copies, modify their attributes as appropriate and submit these copies to this function. See RxClusterSetAttributes for details on changing cluster attributes. Only clusters which are specified with CL_ATTRIB_READ or CL_ATTRIB_WRITE will result in RxCluster actually being present in packets flowing down this pipeline. Other clusters are only present from the point of view of the instancing and DMA code and you will not be able to access them using RxClusterLockRead or RxClusterLockWrite. Visible clusters will be 'broken out' from the usual (complex, packed) format of DMA packet data such that their data is still accessible as a simple, contiguous array of data just like non-PlayStation 2-specific clusters. However, their data will always be flagged as rxCLFLAGS_EXTERNALMODIFIABLE because it is in a fixed location with a fixed size - you cannot free or resize it, but, if CL_ATTRIB_WRITE is set you can modify it. This is useful for things like CPU-side particle system animation. For example, you might request the CL_RGBA and CL_XYZ clusters and specify the CL_XYZ cluster as CL_ATTRIB_READWRITE. Then a node placed after PS2MatInstance.csl and before PS2MatBridge.csl could modify the positions of vertices (particles) before they are uploaded to VU1 (remembering to flush cache on this data of course!). You have to have at least one cluster and can have a maximum of eight (with at most four user-defined clusters). Clusters currently have a maximum stride of one quadword though this limitation will be removed in the future.
|
|
||||||||||||||||
|
RxPipelineNodePS2MatInstanceSetPointListVUBufferSize is used to set the maximum number of vertices for pointlists that may be passed to the VU code section of the pipe containing this node. The stride (in quad words) of the input buffer in vector memory is also set by this function. This function should be called instead of RxPipelineNodePS2MatInstanceSetVUBufferSizes, they should not both be called. Pipelines set up with this function will only be able to handle pointlist objects, not triangle- or line-based objects. For pipelines feeding user supplied VU code, the values to pass to this function may be obtained from the pipeline specific header file created by processing stddata.i. Note that for a pointlist pipeline, the first half of the VU1 code array should be used - i.e the TRANSTRI slots are reused. (see RxPipelineNodePS2MatBridgeSetVU1CodeArray) Note that the buffer size submitted may be rounded down. For pointlists, it will be rounded down to (4n) due to DMA read alignment requirements. This function should be called before unlocking the pipeline containing this node.
|
|
||||||||||||||||||||
|
RxPipelineNodePS2MatInstanceSetVUBufferSizes is used to set the maximum number of triangles (for trilists) and vertices (for tristrips) that may be passed to the VU code section of the pipe containing this node. The stride (in quad words) of the input buffer in vector memory is also set by this function. If this function is not called the defaults required by the standard transforms will be used. For pipelines feeding user supplied VU code, these values may be obtained from the pipeline specific header file created by processing stddata.i Note that the buffer sizes submitted may be rounded down. For trilists, buffer sizes will be rounded to a multiple of four triangles (or twelve vertices) due to DMA read alignment requirements. For tristrips, if your vertices contain any broken-out clusters (that is flagged with CL_ATTRIB_READ or CL_ATTRIB_WRITE in their attributes) then the buffer size will be rounded down to (4n + 2) and if there are no broken-out clusters then (4n). This is due again to DMA read alignment requirements and also internal vertex duplication used to continue tristrips between batches. This function must be called before the pipeline containing this node is unlocked.
|
|
||||||||||||
|
RxPipelineNodePS2ObjAllInOneSetGrouping allows you to specify whether this instance of the PS2ObjAllInOne.csl node will send meshes in packets to pipelines specified by their associated materials, or whether it will send them to the (hopefully connected!) first output of this node. For objects in which all meshes use the same pipeline, it can be more efficient to have those meshes processed by just one pipeline, since passing packets between pipelines can incur a significant cost. If you tell this node to group its meshes, it will dispatch them all to the first output of this node, where the application should arrange that the nodes of a suitable material pipeline are connected. Note that one application of this process might be as a form of LOD - when objects are close up, you may apply localized special effects by giving different meshes within the object different pipelines, but when the object gets far away it becomes less worthy of processor time, so you switch to uniform rendering of the object where all meshes pass down this "atomic rendering pipeline" (which differs from the usual atomic pipeline by containing 'inlined' material rendering nodes). This function can be called when the pipeline node's containing pipeline is unlocked.
|
|
||||||||||||
|
RxPipelineNodePS2ObjAllInOneSetLighting allows you to overload PS2ObjAllInOne.csl with your own lighting system. The Lighting function you pass must have the following format: void RxWorldLightingCallBack *(RwInt32 objectType, void *object) This function should be called after unlocking the pipeline containing this node.
|
© 1993-2003 Criterion Software Limited. All
rights reserved. Built Tue Apr 22 12:46:52 2003. Send Feedback
| Converted from CHM to HTML with chm2web Pro 2.85 (unicode) |