The RtLtMap toolkit contains a suite of functionality for generating lightmaps. The process of lightmap generation consists of two main stages. Firstly, lightmaps need to be allocated and associated with objects, and the UV coordinates for the lightmap pass need to be calculated (see RtLtMapLightMapsCreate). Secondly, color values need to be calculated for lightmap texels and, optionally, vertex prelight colors (see RtLtMapIlluminate).
Lightmaps generated by this toolkit support tristripped geometry (unusual for lightmap implementations) and so will render very quickly, especially on such platforms as PlayStation 2. A few visual artifacts remain due to this tristrip support, though they will, in the vast majority of cases, go unnoticed or easily be worked around.
Lighting calculations support the standard RpLight types, as well as area light sources, specified with normal geometry on a per-material basis (RtLtMapAreaLightGroupCreate). Area lighting can produce very convincing lighting solutions, with subtle gradients and soft shadows.
|
|
RtLtMapIlluminateProgressCallBack is the callback to be called, from within RtLtMapIlluminate, to allow a user to track lighting progress. The progress callback will be called at several stages during lighting, with a different 'message' parameter value used at each stage (see RtLtMapProgressMessage). It will be called at the very start of lighting (for a given RtLtMapLightingSession), before any samples are lit. It will also be called at the very end of lighting, after all samples have been lit. It will be called before and after each lighting 'slice' (see RtLtMapIlluminate) and also after each group of samples have been lit. For lightmapped objects, samples are grouped on a per-polygon basis and for vertex-lit objects, samples are grouped on a per-object basis (see RtLtMapObjectFlags). The progress callback will receive a RwReal value specifying the percentage of samples already lit in the current RtLtMapLightingSession (see RtLtMapLightingSessionGetNumSamples). By returning FALSE, the progress callback may cause early termination of the current lighting 'slice' (this may be used, for example, to keep the time spent lighting each slice fairly constant). There is no default progress callback supplied with RtLtMap.
|
|
|
RtLtMapIlluminateSampleCallBack is the callback to be called, from within RtLtMapIlluminate, for groups of samples in the objects currently being illuminated. For lightmapped objects, samples are grouped on a per-polygon basis and for vertex-lit objects, samples are grouped on a per-object basis (see RtLtMapObjectFlags). This callback will receive an array of color values to fill in, each representing one sample in the current object - this may correspond to a texel in the current object's lightmap or the prelight color of a vertex, depending on whether the object is lightmapped and/or vertex-lit. It will receive positions (in world-space) for each sample and the normal vector (again, in world-space) of each sample (normals are interpolated across polygons for non-flat-shaded materials. See RtLtMapMaterialFlags). For lightmap samples (not vertex-lighting samples), it will receive barycentric coordinates within the current polygon. It will also receive a list of RpLights affecting the current object. The barycentric coordinates may be used, for example, to allow a callback to easily import existing lighting data (e.g from previously generated lightmaps in a different format, or from an art package with lighting functionality). NOTE: The alpha channel of the RwRGBA results array must NOT be modified. These values are used internally and their modification may result in unwanted visual artifacts in the resulting lighting solution. The default RtLtMapIlluminateSampleCallBacks supplied with RtLtMap is RtLtMapDefaultSampleCallBack. This callback performs point and area lighting (the area lights use are those passed to RtLtMapIlluminate).
|
|
|
RtLtMapIlluminateVisCallBack is the callback to be called, from within RtLtMapIlluminate, to determine the visibility between a sample and a light. This callback is called for all samples in the current RtLtMapLightingSession and for each light source which may potentially affect each of those samples (this may not be all the lights in the scene, as some hierarchical culling is performed). Each sample may represent a texel in the current object's lightmap or the prelight color of a vertex, depending on whether the object is lightmapped and/or vertex-lit (see RtLtMapObjectFlags). The callback will receive a pointer to the world of the current RtLtMapLightingSession (this may be used to perform intersection tests), the world-space position of the sample, the world-space position of the light, a pointer to a light and a pointer to an RwRGBAReal result value. If the light pointer is NULL, this means that the current light is an area light (as opposed to an RpLight), of an internal format. The area lights use are those passed to RtLtMapIlluminate. The callback should return FALSE to signify that the light is wholly occluded w.r.t the sample position, otherwise it should return TRUE. Partial degrees of (color-frequency-dependent) occlusion may be expressed by modifying the RwRGBAReal value. This defaults to bright white but may be reduced to signify that the light from the light source should be attenuated. This could be used to take into account light-filtering objects in the scene (such as colored glass or fog). The default RtLtMapIlluminateVisCallBack supplied with RtLtMap is RtLtMapDefaultVisCallBack. This callback performs visibility tests using the line-intersection tests from RtIntersection. It tests for occlusion by RpWorldSectors and RpAtomics and it respects the relevant RtLtMapObjectFlags and RtLtMapMaterialFlags but it does not filter light; visibility is determined to be either one or zero.
|
|
|
RtLtMapLightMapProcessCallBack is the callback to be called, from within RtLtMapLightingSessionLightMapProcess, to allow a lightmap to be process after a lighting session. For some platform, the lightmap needs to be converted before it can be used during rendering. This function allows a post process operation to be performed on the lightmaps before it can be used. The actual operation is platform specific. The callback is only called for lightmaps that were updated from the last lighting session.
|
|
|
RtLtMapMaterialFlags is an enumerated type specifying the different lightmap-related flags which may be applied to materials. These values will be taken into consideration within RtLtMapIlluminate.
|
|
|
RtLtMapObjectFlags is an enumerated type specifying the different lightmap-related flags which may be applied to world sectors and atomics. These values will be taken into consideration within RtLtMapLightMapsCreate and RtLtMapIlluminate.
|
|
|
RtLtMapProgressMessage is an enumerated type identifying the different stages at which the RtLtMapIlluminateProgressCallBack may be called from within RtLtMapIlluminate.
|
|
||||||||||||
|
RtLtMapAreaLightGroupCreate is used to generate a set of area light samples from the geometry in an RtLtMapLightingSession. Area lighting is performed, within RtLtMap, by generating a set of point light 'samples' across the surface of geometry which is flagged as being a light emitter. This set of point lights approximates, to a higher or lower degree, the 'true' emission of light from a surface. The more samples are generated, the more accurate the result will be, but the longer it will take to compute. Each light sample is treated as a point light (similar to an RpLight of type rpLIGHTPOINT) with an inverse square law intensity falloff. It has an associated area of surface which it represents, such that for a sample of unit area and unit brightness, light intensity will be also be unit at unit distance along the sample's normal (which is the normal of the triangle from which it was sourced). This means that, if a scene is uniformly scaled by any factor, the resulting lighting solution should look the same. See RtLtMapIlluminate for further details on how light contributions are summed and post-processed. This function traverses the triangles of the objects specified by the received RtLtMapLightingSession structure. Only atomics flagged as rpATOMICRENDER will be used. Note that the camera member of this structure is ignored, because lights outside of the camera frustum can light geometry within the camera frustum. Area light samples are generated for triangles whose material is flagged with rtLTMAPMATERIALAREALIGHT (see RtLtMapMaterialFlags). Various functions (listed below) can be used to modify the area lighting properties of a given material. This function returns an RtLtMapAreaLightGroup, containing the area light samples, which may later be passed to RtLtMapIlluminate. These containers hierarchically group area light samples, such that they can be efficiently culled during lighting calculations (naively testing visibility from each lightmap sample to every single area light sample in the scene - of which there may be many thousand - can be extremely, and unnecessarily, expensive). Several RtLtMapAreaLightGroup structures may be chained together, such that area light samples sourced from multiple RtLtMapLightingSession's may be passed to RtLtMapIlluminate simultaneously. Each container may have a pointer to an RwFrame, such that, for example, area light samples from multiple worlds, which are connected by portals, or which are composed of atomics and not world sectors, may be used within a single call to RtLtMapIlluminate). The density parameter of this function specifies the number of area light samples to be generated per unit world-space. The higher this value is, the more samples will be generated. If this value is set to zero, a default value will be used, which is twice the lightmap sample density for the world of the current RtLtMapLightingSession. If this value is zero (i.e the world has not yet been used in a call to RtLtMapLightMapsCreate) then a sample density is chosen such that 400 area light samples would fit, in a straight line, into the diagonal 'length' of the world's bounding box. The density value may be modified by material plugin data (see RtLtMapMaterialSetAreaLightDensityModifier) or a global modifier (see RtLtMapSetAreaLightDensityModifier). For triangles within atomics which have multiple morph targets, the positions of the vertices specified in the 'start' morph target of the atomic's interpolator will be used. Other functions available to tweak area lighting calculations are:
|
|
|
RtLtMapAreaLightGroupDestroy is used to destroy an area light samples container created by RtLtMapAreaLightGroupCreate. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapAtomicGetFlags is used to retrieve lightmap-related flags for a given atomic. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapAtomicGetLightMapSize is used to retrieve the size of lightmap to be created for a given atomic. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapAtomicGetNumSamples returns the number of lighting samples in a given atomic. An atomic may have both lightmap and vertex prelight samples (depending on its flags - see RtLtMapObjectFlags - and whether or not it has had a lightmap created for it yet). Note that a returned value of zero does not indicate an error, merely that no lighting samples were found in the supplied atomic. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapAtomicImagePurge destroys the temporary images, used during lightmap illumination, for a specified atomic. Each lightmap has a sample map associated with it, used to enable incremental lighting (see RtLtMapIlluminate). Once lighting is finished, this function may be used to destroy this sample map. The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapAtomicLightMapClear clears the lightmap of a specified atomic. When a lightmap is cleared, the texel values are set to either a black and white checkerboard pattern (useful to clearly see where lightmap texels lie on polygons), if the color parameter is NULL, or to the value of the RwRGBA value pointed to by the color parameter. Additionally, the RwImage associated with the lightmap (used for incremental lighting, see RtLtMapIlluminate) is also cleared. Note that, as several atomics and world sectors may share a single lightmap, calling this function for one object may affect other objects. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapAtomicLightMapDestroy destroys the lightmap (if any) associated with a given atomic. Note that this function destroys the intermediate sample map attached to the object, if it exists. Hence it is not necessary to call RtLtMapAtomicImagePurge before calling this function. The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapAtomicSetFlags is used to set lightmap-related flags for a given atomic. Note that you cannot change the rtLTMAPOBJECTLIGHTMAP flag for an atomic after RtLtMapLightMapsCreate has created a lightmap for that atomic (see RtLtMapObjectFlags). The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapAtomicSetLightMapSize is used to set the size of lightmap to be created for a given atomic. By default, the size of lightmap assigned to an object is determined by a global default value (see RtLtMapLightMapGetDefaultSize), but that value may be overridden on a per-object basis by using this function. Note that you should only call this function before the atomic's lightmap is created by RtLtMapLightMapsCreate, for obvious reasons. The lightmap plugin must be attached before using this function.
|
|
||||||||||||||||||||||||||||||||
|
RtLtMapDefaultSampleCallBack is the default RtLtMapIlluminateSampleCallBack callback, called from within RtLtMapIlluminate. This callback calculates lightmap sample values using standard RpLight lighting equations and area lighting equations. The results, for a scene containing no area lights, should look similar to a scene, with only vertex lighting, which has been tesselated to the resolution of lightmaps. The main visual difference would be that shadows are calculated for lightmaps but not for vertex lighting. This function makes use of the RtLtMapIlluminateVisCallBack passed to RtLtMapIlluminate, for determining visibility between lightmap samples and lights. Object flags (see RtLtMapObjectFlags) and material flags (see RtLtMapMaterialFlags) are taken into account. See RtLtMapIlluminate for further details on lighting calculations. The lightmap plugin must be attached before using this function.
|
|
||||||||||||||||||||||||
|
RtLtMapDefaultVisCallBack is the default RtLtMapIlluminateVisCallBack, called from within RtLtMapIlluminate and RtLtMapDefaultSampleCallBack. This is the default callback used for determining the visibility between lights and sample points. Currently, it returns either complete visibility or complete occlusion. User callbacks could implement color-filtering (due to glass or fog, say) by modifying the value of the RwRGBAReal pointed to by the result parameter. This function performs line intersections tests using the RpCollision plugin and RtIntersection toolkit. PVS information is not currently used (though area lights are culled using PVS information at a higher level in the lighting calculations). See RtLtMapIlluminate for further details on lighting calculations. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapGetAreaLightDensityModifier is used to retrieve the current modifier of the spacing between the area light samples generated by RtLtMapAreaLightGroupCreate. See RtLtMapSetAreaLightDensityModifier for further details. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapGetAreaLightErrorCutoff is used to retrieve the current error tolerance used in enforcing a finite Region Of Influence (R.O.I.) on area light sources. See RtLtMapSetAreaLightErrorCutoff for further details. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapGetAreaLightRadiusModifier is used to retrieve the current global area light source intensity falloff modifier. See RtLtMapSetAreaLightRadiusModifier for further details. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapGetDefaultPrefixString is used to retrieve the default string used to generate lightmap texture names. See RtLtMapSetDefaultPrefixString for further details.
|
|
|
RtLtMapGetLightMapCounter is used to retrieve the counter used to name lightmaps with sequentially increasing numeric suffices. See RtLtMapSetLightMapCounter for further details. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapGetLightMapProcessCallBack query the callback used to process the lightmap after lighting. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapGetMaxAreaLightSamplesPerMesh is used to retrieve the maximum number of area light samples which will be generated, per source RpMesh, by RtLtMapAreaLightGroupCreate. See RtLtMapSetMaxAreaLightSamplesPerMesh for further details. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapGetSliverAreaThreshold is used to retrieve the current threshold area below which triangles are treated as slivers during lightmap illumination. The calculation of normal vectors for triangles of a very small error is subject to the numerical precision limitations of floating-point numbers, hence triangles below a certain area are skipped during lightmap illumination. The lightmap texels (if any) covered by these triangles are filled in from neighboring triangles as a post-process. This function allows to retrieve the threshold area used, in case certain user-created triangles happen to lie unfortunately on the threshold. The symptom of a sliver triangle being lit which should not be lit is usually that a line of lightmap texels on a surface are assigned the incorrect color values (for example, if a sliver has been determined to point in a strange direction, so the lighting calculations may think it is pointing away from a light whilst non-sliver triangles adjacent to it are pointing towards the light). In such a case, increasing the sliver threshold value should fix the problem (see RtLtMapSetSliverAreaThreshold) Note that increasing the threshold too far might make it impossible for the post-process to accurately fill in all unprocessed lightmap texels (resulting in uninitialized lightmap texels). The default sliver area threshold is given by the value of rpLTMAPDEFAULTSLIVERAREATHRESHOLD. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapGetVertexWeldThreshold is used to retrieve the current threshold distance below which triangle vertices are treated as being at the same position during lightmap UV calculation. The calculation of per-vertex lightmap UV coordinates, during RtLtMapLightMapsCreate, makes the assumption that adjacent triangles which have different vertices, but whose vertices share the same position, should be grouped together (and thus be adjacent in) the lightmap of the current object. This means that lightmap texels will be shared across the two triangles. The vertex welding threshold distance is used to determin whether two vertices are at the same position. The distance used should be the same as that used during the export of objects from the user's modelling package. If the threshold is too large, then triangles will be inappropriately grouped, which could cause artifacts during lightmap illumination. If the threshold is too large, then more triangles will be split up than necessary in the object's lightmap, resulting in less efficient use of the lightmap's texels. The default vertex welding threshold distance is given by the value of rpLTMAPDEFAULTVERTEXWELDTHRESHOLD. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapGetVisCallBackCollisionScalar returns the current value of the collision scalar. see RtLtMapSetVisCallBackCollisionScalar for more information on the use of the collision scalar. The lightmap plugin must be attached before using this function.
|
|
||||||||||||||||
|
RtLtMapIlluminate performs illumination of the lightmaps attached to objects within a specified RtLtMapLightingSession. This function traverses the objects specified by the received RtLtMapLightingSession structure. Only atomics flagged as rpATOMICRENDER will be used. Note that the camera member of this structure is used. Lightmaps must have been created, by RtLtMapLightMapsCreate, for all of the sectors and atomics to be illuminated which have the rtLTMAPOBJECTLIGHTMAP flag set. Vertex normals and prelight colors should be present for objects with the rtLTMAPOBJECTVERTEXLIGHT flag set - lightmap and vertex 'sample' colors will both be calculated within this function. Lightmapped objects without vertex normals will be lit as if flat-shaded (i.e polygon normals will be used rather than interpolated vertex normals). The received RtLtMapLightingSession can be used cause this function to light only a subset, or 'slice', of all of the lightmap and prelight samples of the objects contained within the session. This may be useful to display realtime visual updates of the lighting calculations as they are in progress. For example, within an app displaying a lightmapped world, calling RtLtMapIlluminate, with the session's numSamples member set to 1000 and startSample member set to zero, will cause the first 1000 or so samples in the session to be lit (the exact number of samples lit will be returned by RtLtMapIlluminate) and the lightmaps will appear updated onscreen. To light about 1000 samples per frame, the session's startSample member should merely be incremented each frame by the number of samples lit in the previous frame. The total number of samples to be lit in the current session is stored by RtLtMapIluminate in the totalSamples member of the session (see also RtLtMapLightingSessionGetNumSamples). Note that this sort of incremental lighting updates lightmap rasters after each 'slice', such that the effect of moved lights will be visible in the regions where the light received from the light has noticeably increased or decreased. Internally, RwImages are used to keep track of state information such that this incremental lighting is possible. When lightmaps are loaded from disk, these images are not present, hence RtLtMapIlluminate will clear each lightmap before performing the first illumination 'slice' that affects it. Note also that it is important not to change the world, camera or object lists in the lighting session between slices, or RtLtMapIlluminate will not be able to correctly keep track of progress. RwCameraClone may be used to create an unchanging clone camera for the session, such that the original camera (that which is actually used to render into the currently displayed framebuffer) may be moved around during lighting without causing problems. In addition to a set of objects to be illuminated, the RtLtMapLightingSession structure contains three (optional) pointers to callbacks which may be used to overload the lighting process. The RtLtMapIlluminateSampleCallBack may be used to completely change the calculation of lightmap or vertex prelight samples. The RtLtMapIlluminateVisCallBack (which is called from within the default sample callback) may be used to alter visibility calculations (visibility being between lights and lightmap or vertex prelight sample points). The RtLtMapIlluminateProgressCallBack may be used to track lighting progress. If any of these pointers in the lighting session are NULL, the default callback is used instead (note that there is no default progress callback). The default sample and vis callbacks (RtLtMapDefaultSampleCallBack and RtLtMapDefaultVisCallBack) implement lighting models for all RpLight types and additionally area light sources. Sets of area light source samples (created by RtLtMapAreaLightGroupCreate) may be passed to this function, to be used during lighting calculations. Light gathered from area light sources is post-processed using a logarithmic scaling function which takes into account the relationship between light intensity and the eye's perception of brightness. This allows a high dynamic range of intensity, from 1 to 1024 (in units of the emitter intensity specified by RtLtMapMaterialSetAreaLightColor), with 255 mapping to 204. See RtLtMapAreaLightGroupCreate for further details. Although lightmaps are illuminated for only a subset of the objects in a world, all of the objects in the world will be used during the lighting calculations. Hence a non-lightmapped atomic in the world will still cast shadows and shadows may be cast from out-of frustum lights, by out-of-frustum objects. The flags rpGEOMETRYLIGHT and rpWORLDLIGHT are respected during lighting. Only the lightmaps of atomics and sectors which are flagged as being lit will be affected by RpLight's during the lighting calculations. Similarly, only RpLight's flagged with rpLIGHTLIGHTATOMICS will affect the lightmaps of atomics and only those flagged with rpLIGHTLIGHTWORLD will affect the lightmaps of world sectors. RtLtMapIlluminate creates collision data for atomics and world sectors if it is not present already (see RpCollisionGeometryBuildData). If this data cannot be built then lighting calculations will proceed much more slowly. The lightmaps can be sampled at a higher resolution and sampled down to a lower resolution for display for better results. The sampling resolution can be increased by setting the superSample parameter > 1. This sets the sampling resolution as a scale relative to the lightmap's size. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapImagesPurge destroys the temporary images, used during lightmap illumination, for the objects specified by an RtLtMapLightingSession. This function traverses the objects specified by the received RtLtMapLightingSession structure. Only atomics flagged as rpATOMICRENDER will be used. Note that the camera member of this structure is ignored. Each lightmap has an RwImage associated with it, used to enable incremental lighting (see RtLtMapIlluminate). Once lighting is finished, this function may be used to destroy these images. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapLightingSessionDeInitialize is used to de-initialize a RtLtMapLightingSession structure to a default form. This function sets the sessions' camera, atomicList, sectorList, world and callback pointers to NULL. The startSample, numSamples and totalSamples members are also set to zero. Temprary working memory are de-allocated within this functions. This function must be called for every session if it is longer required to avoid memory leakage. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapLightingSessionGetNumSamples calculates the number of lighting samples represented by the objects in a specified RtLtMapLightingSession. This function traverses the objects specified by the received RtLtMapLightingSession structure. Only atomics flagged as rpATOMICRENDER will be used. Note that the camera member of this structure is used. As with RtLtMapIlluminate, this function fills in the totalSamples member of the received lighting session. The value calculated is the same as that calculated by RtLtMapIlluminate. Both lightmap samples and vertex lighting samples are taken into account. Camera frustum culling is done on a per-object basis, hence there may be samples for which no lighting calculations are actually done within RtLtMapIlluminate (these are still counted in tracking lighting progress, though - see also RtLtMapIlluminateProgressCallBack). Note that a returned value of zero does not indicate an error, merely that no (visible) lighting samples were found in the supplied lighting session. The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapLightingSessionInitialize is used to initialize an RtLtMapLightingSession structure to a default form. This function sets the sessions' camera, atomicList, sectorList and callback pointers to NULL. The startSample, numSamples and totalSamples members are also set to zero. The session's world pointer is set up from a parameter, since a session is not usable with a NULL world pointer. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapLightingSessionLightMapProcess is the function to be called to perform any operation on the lightmap data. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapLightMapGetDefaultSize is used to retrieve the size of lightmaps which will subsequently be created. The global default lightmap size value may be overridden on a per object basis (see RtLtMapAtomicSetLightMapSize). The default size of lightmaps on startup is given by the value rpLTMAPDEFAULTLIGHTMAPSIZE and can be overridden with this function. Lightmaps are always square and must have sides a power of two in length. The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapLightMapsClear clears the lightmaps of the objects in an RtLtMapLightingSession. This function traverses the objects specified by the received RtLtMapLightingSession structure. Only atomics flagged as rpATOMICRENDER will be used. Note that the camera member of this structure is used. When a lightmap is cleared, the texel values are set to either a black and white checkerboard pattern (useful to clearly see where lightmap texels lie on polygons), if the color parameter is NULL, or to the value of the RwRGBA value pointed to by the color parameter. Additionally, the RwImage associated with the lightmap (used for incremental lighting, see RtLtMapIlluminate) is also cleared. The lightmap plugin must be attached before using this function.
|
|
||||||||||||||||
|
RtLtMapLightMapsCreate creates lightmaps for the objects specified within an RtLtMapLightingSession. This function traverses the objects specified by the received RtLtMapLightingSession structure. Only atomics flagged as rpATOMICRENDER will be used. Note that the camera member of this structure is used. Any given atomic or world sector may reference at most one lightmap. A single lightmap may, however, be referenced by multiple such objects. Note that this lightmap 'sharing' will only occur between the objects specified within the received RtLtMapLightingSession. Hence, if objects are passed to this function one by one, no lightmap sharing will occur. In creating a lightmap for a given object, each triangle in the object must be placed within the lightmap (i.e have its second set of UV coordinates set up). This process is fairly complex and slow, due to two considerations. Firstly, to minimize the usage of video memory by lightmaps, object triangles must be packed into lightmaps as tightly as possible - this is a variant of the 'knapsack problem', which is non-trivial. Secondly, this implementation of lightmaps is designed to work with tristripped geometry, for efficiency (most lightmap implementations require trilist geometry as it simplifies many aspects of lightmap generation, such as this one, greatly). This requires analysing surface topology and taking several precautions to avoid visual artifacts, but the result is that fewer lightmap texels are consumed per triangle (since adjacent triangles can share lightmap texels) and that lightmapped geometry renders much more quickly (especially on platforms such as PlayStation 2). Lightmap UV coordinates are calculated such as to distribute lighting sample points (lightmap texels) uniformly over geometry, at a density (in world- space) specified by the density parameter of this function. This density may be modified on a per-material basis (see RtLtMapMaterialSetLightMapDensityModifier). If, given the specified lightmap density, a particular sector or atomic contains triangles of too great an area to fit into a single lightmap, the lightmap density of those triangles is halved. This is repeated until the triangles fit or the process fails. Hence, it is recommended to choose lightmap density and object size (e.g by controlling BSP sectorization) such that this shrinkage need not occur (a rough rule of thumb is to ensure that "density*objectSize < lightMapSize"). Debug stream messages will be issued if it does. The size of lightmap assigned to each object is determined by a global value (see RtLtMapLightMapSetDefaultSize), which may be overridden on a per-object basis (see RtLtMapAtomicSetLightMapSize). Lightmaps are named automatically (see RtLtMapGetDefaultPrefixString) but they may be renamed (see RpLtMapAtomicSetLightMap) and/or otherwise modified before they are saved to disk. Lightmaps automatically get added to the current texture dictionary on creation. By default, this function will initialize lightmap colors to a black and white checkerboard. If the color parameter is non-NULL, lightmaps will be cleared to this color instead (note that the alpha channel is set to an internally-used value in all cases). In addition to creating lightmaps, this function also changes the object pipelines of the affected sectors and atomics, setting them to use platform-specific lightmap rendering pipelines. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapLightMapsDestroy destroys the lightmaps (if any) associated with the objects in an RtLtMapLightingSession. This function traverses the objects specified by the received RtLtMapLightingSession structure. Only atomics flagged as rpATOMICRENDER will be used. Note that the camera member of this structure is used. Note that this function destroys the intermediate sample map attached to the objects, if they exist. Hence it is not necessary to call RtLtMapImagesPurge before calling this function. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapLightMapSetDefaultSize specifies the size of lightmaps which will subsequently be created. The global default lightmap size value may be overridden on a per object basis (see RtLtMapAtomicSetLightMapSize). The default size of lightmaps on startup is given by the value rpLTMAPDEFAULTLIGHTMAPSIZE and can be overridden with this function. Lightmaps are always square and must have sides a power of two in length. This function should be called before RtLtMapLightMapsCreate if it is to have any effect. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapMaterialGetAreaLightColor is used to retrieve the color of area light samples generated by RtLtMapAreaLightGroupCreate from triangles with this material (and flagged as being area light emitters with rtLTMAPMATERIALAREALIGHT). The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapMaterialGetAreaLightDensityModifier is used to retrieve the area light sample density modifier for a material. The area light sample density modifier of a material is used as a multiplicative modifier to the default value. Hence, setting a value of 2 will double the (linear) density of area light samples, halving the distance between adjacent samples and resulting in approximately four times as many samples being generated (from triangles using this material). The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapMaterialGetAreaLightRadiusModifier is used to retrieve the area light radius modifier for a material. The radius modifier of a light-emitting material effectively reduces or increases the intensity of emitted light. As an example, if the modifier is changed from one to two then the same intensity of light will now be received at twice the distance from the light source. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapMaterialGetFlags retrieves the lightmap-related flags of a given material. Material flags control material properties relevant to lighting calculations. See RtLtMapMaterialFlags for further details. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapMaterialGetLightMapDensityModifier retrieves the lightmap density modifier of a given material. The lightmap density modifier multiplies the default lightmap sample density used, within RtLtMapLightMapsCreate, for creating lightmaps. This is useful for getting large areas sampled at a low frequency, thus reducing the number of required lightmap texels and speeding up lighting calculations. This function should be called before a call to RtLtMapLightMapsCreate in order to have any effect. The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapMaterialSetAreaLightColor is used to set the color of area light samples generated by RtLtMapAreaLightGroupCreate from triangles with this material (and flagged as being area light emitters with rtLTMAPMATERIALAREALIGHT). Whilst the color of an area light emitter is only specified using a limited-range RwRGBA value, this may be effectively reduced or increased in intensity through RtLtMapMaterialSetAreaLightRadiusModifier, which takes a high-dynamic-range RwReal value. The default color of an area light emitter is {255, 255, 255}. The alpha value is currently unused. Note that to have any effect, this function must be used before a call to RtLtMapAreaLightGroupCreate. The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapMaterialSetAreaLightDensityModifier is used to modify the spacing of area light samples generated by RtLtMapAreaLightGroupCreate from triangles with this material (and flagged as being area light emitters with rtLTMAPMATERIALAREALIGHT). The area light sample density modifier of a material is used as a multiplicative modifier to the default value. Hence, setting a value of 2 will double the (linear) density of area light samples, halving the distance between adjacent samples and resulting in approximately four times as many samples being generated (from triangles using this material). Overall brightness should not be affected by the density modifier, just the quality (accuracy/softness) of the resultant lighting solution. Note that to have any effect, this function must be used before a call to RtLtMapAreaLightGroupCreate. The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapMaterialSetAreaLightRadiusModifier is used to modify the falloff of light emitted from triangles with this material. The radius modifier of a light-emitting material can be used to effectively reduce or increase the intensity of emitted light. As an example, if the modifier is changed from one to two then the same intensity of light will now be received at twice the distance from the light source. The default modifier for a material is one (identity). Note that to have any effect, this function must be used before a call to RtLtMapAreaLightGroupCreate. The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapMaterialSetFlags sets the lightmap-related flags of a given material. Material flags control material properties relevant to lighting calculations. See RtLtMapMaterialFlags for further details. The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapMaterialSetLightMapDensityModifier sets the lightmap density modifier of a given material. The lightmap density modifier multiplies the default lightmap sample density used, within RtLtMapLightMapsCreate, for creating lightmaps. This is useful for getting large areas sampled at a low frequency, thus reducing the number of required lightmap texels and speeding up lighting calculations. This function should be called before a call to RtLtMapLightMapsCreate in order to have any effect. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapSetAreaLightDensityModifier is used to modify the spacing of area light samples generated by RtLtMapAreaLightGroupCreate. The area light sample density modifier is used as a multiplicative modifier to the default value. Hence, setting a value of 2 will double the (linear) density of area light samples, halving the distance between adjacent samples and resulting in approximately four times as many samples being generated. Overall brightness should not be affected by the density modifier, just the quality (accuracy/softness) of the resultant lighting solution. The default modifier is one (identity). See also RtLtMapMaterialSetAreaLightDensityModifier. The per-material modifier multiplies this global modifier. Note that to have any effect, this function must be used before a call to RtLtMapAreaLightGroupCreate. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapSetAreaLightErrorCutoff is used to determine the error tolerance in enforcing a finite Region Of Influence (R.O.I.) on area light sources. Area light samples are treated, during lighting calculations, as having an inverse square law for light intensity falloff. For efficiency, area light samples (and also hierarchical groups of samples) are given a finite R.O.I, so that visibility does not have to be tested between all area lights and all sample points in the scene. The error tolerance value specifies the intensity of an area light source at the limit of its R.O.I. In other words, light intensity will drop with increasing distance from the light source, until it reaches the limit of the light's R.O.I. - at which point the intensity will immediately drop to zero, introducing a discontinuity. The magnitude of this discontinuity if the error tolerance value. Hence, a larger error tolerance value will reduce the R.O.I.s of area light sources (which will accelerate lighting calculations) but may result in visible discontinuities in lightmaps. The error tolerance value is given in terms of perceived brightness (which is related logarithmically to light intensity, as described in RtLtMapIlluminate) and should be in the range zero to 255. This corresponds to RwRGBA values in the resultant lightmaps. The default error tolerance value is given by rpLTMAPDEFAULTrecipAreaLightROICutoff. Note that to have any effect, this function must be used before a call to RtLtMapAreaLightGroupCreate. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapSetAreaLightRadiusModifier is used to modify the falloff of all area light sources. The area light source radius modifier can be used to effectively reduce or increase the intensity of light emitted from area light sources. As an example, if the modifier is changed from one to two then the same intensity of light will now be received at twice the distance from a light source. The default modifier is one (identity). See also RtLtMapMaterialSetAreaLightRadiusModifier. The per-material modifier multiplies this global modifier. Note that to have any effect, this function must be used before a call to RtLtMapAreaLightGroupCreate. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapSetDefaultPrefixString is used to set the default string used to generate lightmap texture names. When lightmaps are created (see RtLtMapLightMapsCreate), their name is automatically generated by appending a counter value (incremented by one for each new lightmap generated) to a global 'prefix' string. For example, if the current prefix string is "ltmp", the fifth lightmap to be created will be named "ltmp0005" (note that the string and number are padded with zeroes to be 8 characters long). Calling this function resets the counter value to zero. By varying prefix strings, the user may avoid naming clashes between the lightmaps in different worlds (if two worlds are to be resident in memory simultaneously). Alternatively, lightmap texture names may be edited directly (see RpLtMapAtomicGetLightMap). The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapSetLightMapCounter is used to modify the counter used to name lightmaps with sequentially increasing numeric suffices. When lightmaps are created (see RtLtMapLightMapsCreate), their name is automatically generated by appending a counter value (incremented by one for each new lightmap generated) to a global 'prefix' string. For example, if the current prefix string is "ltmp", the fifth lightmap to be created will be named "ltmp0005" (note that the string and number are padded with zeroes to be 8 characters long). The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapSetLightMapProcessCallBack sets the callback used to process the lightmap after lighting. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapSetMaxAreaLightSamplesPerMesh is used to limit the number of area light samples generated, per source RpMesh, by RtLtMapAreaLightGroupCreate. This limit is useful to semi-automatically reduce the area light sample density for large polygons, whilst leaving smaller polygons with a high sample density. For a given light-emitting object, increasing the number of area light samples soon becomes a case of 'diminishing returns' with respect to the quality of the resultant lighting solution. Since a world-space sample density is used to generate area light samples, large polygons can end up with huge numbers of samples, most of which contribute little to improving lighting quality - this per-mesh limit should help avoid this occurring. When area light samples have been created for a mesh and it is found that there are too many samples, the sample density value is decreased until an acceptable number of samples is generated. The distribution of samples within the mesh remains even. The default limit value is given by rpLTMAPDEFAULTMAXAREALIGHTSAMPLESPERMESH. Note that to have any effect, this function must be used before a call to RtLtMapAreaLightGroupCreate. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapSetSliverAreaThreshold is used to set the threshold area below which triangles are treated as slivers during lightmap illumination. The calculation of normal vectors for triangles of a very small error is subject to the numerical precision limitations of floating-point numbers, hence triangles below a certain area are skipped during lightmap illumination. The lightmap texels (if any) covered by these triangles are filled in from neighboring triangles as a post-process. This function allows to change the threshold area used, in case certain user-created triangles happen to lie unfortunately on the threshold. The symptom of a sliver triangle being lit which should not be lit is usually that a line of lightmap texels on a surface are assigned the incorrect color values (for example, if a sliver has been determined to point in a strange direction, so the lighting calculations may think it is pointing away from a light whilst non-sliver triangles adjacent to it are pointing towards the light). In such a case, increasing the sliver threshold value should fix the problem. Note that increasing the threshold too far might make it impossible for the post-process to accurately fill in all unprocessed lightmap texels (resulting in uninitialized lightmap texels). The default sliver area threshold is given by the value of rpLTMAPDEFAULTSLIVERAREATHRESHOLD. This function should be called before a call to RtLtMapIlluminate in order to have any effect. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapSetVertexWeldThreshold is used to set the threshold distance below which triangle vertices are treated as being at the same position during lightmap UV calculation. The calculation of per-vertex lightmap UV coordinates, during RtLtMapLightMapsCreate, makes the assumption that adjacent triangles which have different vertices, but whose vertices share the same position, should be grouped together (and thus be adjacent in) the lightmap of the current object. This means that lightmap texels will be shared across the two triangles. The vertex welding threshold distance is used to determin whether two vertices are at the same position. The distance used should be the same as that used during the export of objects from the user's modelling package. If the threshold is too large, then triangles will be inappropriately grouped, which could cause artifacts during lightmap illumination. If the threshold is too large, then more triangles will be split up than necessary in the object's lightmap, resulting in less efficient use of the lightmap's texels. The default vertex welding threshold distance is given by the value of rpLTMAPDEFAULTVERTEXWELDTHRESHOLD. This function should be called before a call to RtLtMapLightMapsCreate in order to have any effect. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapSetVisCallBackCollisionScalar sets the collision scalar used by RtLtMapDefaultVisCallBack to avoid self collision with area lights. The threshold is used to ignore polygons near the light position. Collisions that occur withing the threshold are ignored. This is used when performing area lighting to avoid shadows being cast by the area light geometry itself. 0.0f corresponds to all collisions being ignored, and 1.0f corresponds to no collisions being ignored. The default value is 0.95f. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapTexDictionaryCreate creates a texture dictionary containing the lightmaps associated with the objects in an RtLtMapLightingSession. This function traverses the objects specified by the received RtLtMapLightingSession structure. Only atomics flagged as rpATOMICRENDER will be used. Note that the camera member of this structure is ignored (it is assumed that texture dictionaries are 'view-independent', as it were). If no lightmaps are found, this function will return NULL. It is important to note that the data stored in the texture dictionary is in a platform-dependent form. An object's lightmap may be converted into a (platform-independent) RwImage by the user (see RpLtMapAtomicGetLightMap). Note that it is the user's responsibility to add the lightmaps back to the current texture dictionary (if appropriate) and to destroy the returned texture dictionary. Failing to do so correctly may result in a crash or leaks on app shutdown. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapWorldSectorGetFlags is used to retrieve lightmap-related flags for a given world sector. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapWorldSectorGetLightMapSize is used to retrieve the size of lightmap to be created for a given world sector. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapWorldSectorGetNumSamples returns the number of lighting samples in a given world sector. A world sector may have both lightmap and vertex prelight samples (depending on its flags - see RtLtMapObjectFlags - and whether or not it has had a lightmap created for it yet). Note that a returned value of zero does not indicate an error, merely that no lighting samples were found in the supplied sector. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapWorldSectorImagePurge destroys the temporary images, used during lightmap illumination, for a specified world sector. Each lightmap has a sample map associated with it, used to enable incremental lighting (see RtLtMapIlluminate). Once lighting is finished, this function may be used to destroy this sample map. The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapWorldSectorLightMapClear clears the lightmap of a specified world sector. When a lightmap is cleared, the texel values are set to either a black and white checkerboard pattern (useful to clearly see where lightmap texels lie on polygons), if the color parameter is NULL, or to the value of the RwRGBA value pointed to by the color parameter. Additionally, the RwImage associated with the lightmap (used for incremental lighting, see RtLtMapIlluminate) is also cleared. Note that, as several atomics and world sectors may share a single lightmap, calling this function for one object may affect other objects. The lightmap plugin must be attached before using this function.
|
|
|
RtLtMapWorldSectorLightMapDestroy destroys the lightmap (if any) associated with a given world sector. Note that this function destroys the intermediate sample map attached to the object, if it exists. Hence it is not necessary to call RtLtMapWorldSectorImagePurge before calling this function. The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapWorldSectorSetFlags is used to set lightmap-related flags for a given world sector. Note that you cannot change the rtLTMAPOBJECTLIGHTMAP flag for a world sector after RtLtMapLightMapsCreate has created a lightmap for that sector (see RtLtMapObjectFlags). The lightmap plugin must be attached before using this function.
|
|
||||||||||||
|
RtLtMapWorldSectorSetLightMapSize is used to set the size of lightmap to be created for a given world sector. By default, the size of lightmap assigned to an object is determined by a global default value (see RtLtMapLightMapGetDefaultSize), but that value may be overridden on a per-object basis by using this function. Note that you should only call this function before the sector's lightmap is created by RtLtMapLightMapsCreate, for obvious reasons. The lightmap plugin must be attached before using this function.
|
© 1993-2003 Criterion Software Limited. All
rights reserved. Built Tue Apr 22 12:46:59 2003. Send Feedback
| Converted from CHM to HTML with chm2web Pro 2.85 (unicode) |