The intensity of the light points in a pfLPointState can be attenuated using pfLPStateVal(), as follows:

pfLPStateVal(lpstate, PFLPS_INTENSITY, intensity)

The intensity value, intensity, must range between 0 and 1; 1, no attenuation, is the default.

The intensity of each light point is defined by its four component colors.

Each light point has a normal, which defines the direction of its emanation. By default, all of the light points in a pfLPointState point in the same direction. That direction is defined as the “front” of the light point.

If all light points in a pfGeoSet share the same normal, use the PFGS_OVERALL attribute to optimize the light point computation.

If the light points are directional, the pfGeoSet attributes must specify normals.

pfLPStateMode(lpstate, PFLPS_DIR_MODE, mode);

pfLPStateMode(PFLPS_SHAPE_MODE, mode);

The emanation shape is an elliptical cone, as shown in Figure 21-2.

Figure 21-2. Attenuation Shape

Optionally, the intensity of light can fall off from the normal to the edge of the cone.

The direction of emanation is defined along the Y axis and the shape is defined in the local coordinate system. The coordinate system is rotated so that the Y axis aligns with the normal of each light point.

To specify the shape of emanation, use the following method:

pfLPStateShape(lpstate, horiz, vert, roll, falloff, ambient)

Shape

horiz and vert are total-angles (not angles to the normal) in degrees, which specify the horizontal and vertical dimensions of the cone about the normal. The maximum value for these angles is 180 degrees, which creates a non-directional light point. The default values for horiz and vert is 90 degrees.

---

Tip: A symmetric cone (where horiz and vert are equal) is faster to compute than an asymmetric cone.

---

Falloff

When the vector from the light's position to the eye point is outside the cone, the light point's intensity is ambient. The default ambient value is 0.

If the vector from the light's position to the eye point is within the cone, the intensity of the light point is based on the angle between the normal and that vector. The intensity values range from 1.0, when the eye point lies on the normal, to ambient, at the edge of the cone. How the light attenuates between the normal and the edge of the cone is specified by falloff.

falloff is an exponent that modifies the light point's intensity. A value of 0 indicates that there is no falloff; a value of 1, the default, indicates a linear falloff; values greater than 1 indicate a progressively greater geometric falloff, as shown in Figure 21-3.

Figure 21-3. Attenuation of Light

The distance between the light point and the eye point is used when computing the light point's size and intensity through fog. Since these calculations are intensive, OpenGL Performer provides an approximation for the distance between the light point and the eye point using the following method:

pfLPState(lpstate, PFLPS_RANGE_MODE, mode)

The mode value can be one of the following:

Light points are visible at greater distance than non-emissive polygons. For that reason, the light points appear to punch through fog. To account for this higher visibility, you can supply a punch-through value in the following method:

pfLPStateVal(PFLPS_FOG_SCALE, punch-through);

punch-through is a float that is multiplied times the distance. When punch-through is less than 1.0, the product of the distance and the punch-through value is less than the distance. The revised distance is used in calculating the apparent brightness of the light point; when the punch-through is less than 1.0, the light point appears brighter than it otherwise would. The default punch-through value is 0.25.

pfLPStateMode(lpstate, PFLPS_FOG_MODE, mode);

Light points can exhibit perspective behavior. The following method sets the size of all the light points in a pfGeoSet:

pfLPStateVal(lpstate,PFLPS_SIZE_ACTUAL, real-size); 

real-size is a float that is multiplied times the distance. When real-size is less than 1.0, the product of the distance and the real-size value is less than the distance. The revised distance is used in calculating the apparent size of the light point; when the real-size is less than 1.0, the light point appears larger than it otherwise would. The default real-size value is 0.25.

pfLPStateVal(lpstate,PFLPS_SIZE_MIN_PIXEL, min-size);
pfLPStateVal(lpstate,PFLPS_SIZE_MAX_PIXEL, max-size);

pfLPStateVal(lpstate, PFLPS_SIZE_DIFF_THRESH, threshold);

pfLPStateMode(lpstate, PFLPS_SIZE_MODE, mode);

You can enhance the illusion of perspective by making the light point become more and more transparent as it recedes from view using the following method:

pfLPStateVal(lpstate,PFLPS_TRANSP_PIXEL_SIZE, transp-size);

transp-size is a light point size. When the actual size is smaller than transp-size, the light point becomes transparent.

Using fading to simulate perspective is often more realistic than shrinking the light point size; fading avoids the aliasing problems that occur when light points become too small.

Max(clamp, 1-scale*(transp-size - computed-size)^exp)

pfLPStateVal(lpstate, PFLPS_TRANSP_EXPONENT, exp);
pfLPStateVal(lpstate, PFLPS_TRANSP_SCALE, scale);
pfLPStateVal(lpstate, PFLPS_TRANSP_CLAMP, clamp);

pfLPStateMode(lpstate, PFLPS_TRANSP_MODE, mode)

On InfiniteReality, light points of a given size, up to 100 multisamples, have the same number of multisamples even when the light points cross multiple pixels.

The intensity of a light point is defined by its alpha value. If pfTransparency is set to PFTR_MS_ALPHA_MASK, the alpha value modifies the number of multisamples lit in a light point. For example, if alpha= 0.5, size = 1.0, and the number of multisamples per pixel is 8, the number of illuminated multisamples per the light point is 3.0, as shown in Figure 21-4.

Figure 21-4. Lit Multisamples

The area of a circle with diameter 1.0 is 0.785. The number of multisamples per pixel is given in the frame buffer configuration. If there are 8 multisamples, only 0.785 of them, about 6, are in the light point. Since alpha = 0.5, only half of the 6 multisamples are actually lit.

pfCalligMultisample() tells pfCalligraphic how many multisamples are used in the specified video channel. pfGetCalligMultisample() returns the current setting. Make this call as soon as the information is known or changed.

As with any other OpenGL Performer process, callback functions can configure the process stages using the following:

pfStageConfigFunc(-1, PFPROC_LPOINT, ConfigLPoint);
pfConfigStage(-1, PFPROC_LPOINT | PFPROC_XXX ....);
pfChanTravFunc(chan, PFTRAV_LPOINT, LpointFunc);

pfStageConfigFunc() specifies a callback function, and pfConfigStage() triggers it at the start of the current application frame; both are methods in pfConfig. Configuration callbacks are typically used for process initialization; for example, they are used to do the following:

pfStageConfigFunc() identifies the OpenGL Performer stages, such as PFPROC_ISECT, PFPROC_APP, and PFPROC_DBASE, to configure.

This section explains how the light point process works. All the functions exist in the API; however, all of the processing is done automatically by OpenGL Performer.

---

Note: Light point processing is not done automatically if your application is only using the libpr process model.

---

If the light point process is enabled, a special bin, PFSORT_LPSTATE_BIN, is created to sort all of the pfGeoSets that have a pfLPointState attached to their pfGeoState. This bin is directly used as a display list, LPointBinDL, as shown in Example 21-2.

All bins, except PFSORT_LPSTATE_BIN, are handed to the DRAW process. The DRAW process, after rendering everything in the other bins, renders a ring display list, called DrawRingDL, as shown in Example 21-2. The ring display list contains a synchronization mechanism: the DRAW process waits until it sees the PFDL_END_OF_FRAME token.

/* open the draw ring display list */
pfOpenDList(DrawRingDL);
 
/* preprocess the light points bin. */
/* so the results go in the DrawRingFL */
pfPreprocessDList(LPointBinDL,PFDL_PREPROCESS_LPSTATE);
 
/* Signal the end of the list to the Draw process */
pfAddDListCmd(PFDL_END_OF_FRAME);
 
/* close the draw display list */
pfCloseDList(DrawRingDL);

Table 21-1 summarizes the differences be tween raster and calligraphic displays.

Whenever the calligraphic mode renders a black pixel to the screen, it is completely transparent and the raster image shows through.

When a pixel on the screen is targeted for raster and calligraphic light, both the raster and calligraphic light points are displayed at the same pixel thus making it large (raster) and bright (calligraphic).

A Light Point Board (LPB) is a circuitry card that enables the rendering of calligraphic lights by providing the interface with a calligraphic display. The LPB is configured as follows:

The configuration in Figure 21-5 shows the following:

All the calligraphic light point information is computed by the light point process and goes directly to the LPB. The only missing information is knowing how much of each light point can be seen. To compute that value, the following events take place:

The graphic pipe takes great care that the number of multisamples covered is a constant wherever the light point is. The number of multisamples is not constant after the footprint covers more than 100 multisamples, however. A footprint can cover numerous pixels but is limited to 256 multisamples by the LPB.

pfCalligZFootPrintSize() sets the diameter of the footprint and pfGetCalligZFootPrintSize() returns the diameter. The number of multisamples covered by a footprint is equal to the following:

(n x size2)/(4 x ms)

ms is the number of multisamples per pixel.

To use calligraphic light points, you have to configure the channels on the LPB board and the corresponding channels using ircombine. ircombine operates on the following:

You must also enable the channels on the LPB board before starting the application.

OpenGL Performer does not provide direct access to the LPB drivers. You can, however, write a program that does.

Now, in OpenGL Performer a few steps are still necessary.

You now have calligraphic light points in your application if you have calligraphic light points in your database.

Customizing LPB Initialization

Instead of using the default initialization, OpenGL Performer provides a set of functions that allow your application to customize the initialization of the LPB.

pfInitBoard() opens the LPB device and retrieves the current configuration. This function returns TRUE if successful, FALSE otherwise. You can also use pfIsBoardInit() to determine if the board has been initialized. Each LPB must be initialized before calling pfConfig().

pfCalligCloseBoard() closes the device.

---

Note: The board number and the pipe number are the same because there is only one board per pipe.

---

To access to the LPB directly, return its ID using pfGetCalligDeviceID(). The ID allows you to make direct calls to the LPB driver.

pfGetCalligInfo() returns a pointer to the configuration information structure maintained by the LPB driver. To use this structure, LPB_info, you must include the driver lpb.h file before any OpenGL Performer include files.

---

Note: lpb.h is not distributed with OpenGL Performer; it is part of the LPB driver distribution.

---

Once a board is initialized, you can find out how much memory is available and allocate it among all of the enabled channels on the pipe. You can return the total amount of LPB memory in bytes by calling pfGetCalligBoardMemSize().

By default, each channel receives the same amount of memory. To set up a different partitioning of memory, use pfCalligPartition().

You can attach a pfCalligraphic to a specific pfChannel using the following code:

pfCalligraphic *callig = pfNewCallig(arena) pfCalligChannel(callig, pipe, chan)

callig can then be attached to the pfPipeVideoChannel using pfPVChanCallig().

You can also set the pfCalligraphic on individual pfChannels using pfChanCallig(). You must enable calligraphic light point processing on the specified channels so the GangSwap mechanism is correctly handled by OpenGL Performer, as follows:

pfChanCalligEnable(chan, 1);

---

Note: The video channel number does not have to be the same channel number as the calligraphic board.

---

pfCalligWin() changes the resolution of the X and Y data accepted by the projector. The default values are for an EIS projector (2^16). If you have a conversion interface between the LPB and your projector, the scaling may already be done by the conversion interface. You can use pfCalligWin() to display calligraphic points on only part of the screen or to make multiple viewports.

pfCalligXYSwap() switches the X and Y axes in the display. You can also reverse the X or Y axes by giving negative width and height values in pfCalligWin().

Some display systems, such as the EIS projector, can calculate the following:

If your system cannot perform those calculations, the light point board can calculate those values for your application.

typedef enum {
    pfXSlewQuality0 = 0, /* High quality on the X axis */
    pfXSlewQuality1 = 1, /* Medium quality on the X axis */
    pfXSlewQuality2 = 2, /* Low quality on the X axis */
    pfYSlewQuality0 = 3, /* High quality on the Y axis */
    pfYSlewQuality1 = 4, /* Medium quality on the Y axis */
    pfYSlewQuality2 = 5, /* Low quality on the Y axis */
    pfDefocusQuality0 = 6,/* High quality if focus change */
    pfDefocusQuality1 = 7 /* Medium and Low quality if focus change */
} pfCalligSlewTableEnum;

typedef enum {
    pfRedGammaTable = 0,
    pfGreenGammaTable = 1,
    pfBlueGammaTable = 2
} pfCalligGammaTableEnum;

Like raster lights, calligraphic light points can have a callback function attached to the pfLPointState that can occur before (PRE) or after (POST) the light point processing. The calligraphic and raster callback functions compute different parameters.

If the stress test determines that a calligraphic light point is not going to be drawn as a raster light point, the calligraphic callback is not be called; the raster callback is called instead if set. For more information about the stress test, see “Significance”.

To install a calligraphic callback on a pfLPointState, you use a line of code similar to the following:

pfCalligFunc(lpstate, (void *) yourCallback(pfCalligData*), 
    void **userData);

userData is a user pointer given to your callback identifying the callback function and the following structure:

typedef struct {
    pfLPointState   *lpstate;  /* Read Only LPState */
    pfGeoSet        *geoset;   /* Read Only GeoSet */
    void            *userData; /* Provided when setting the callback */
    unsigned short  *index;    /* Read Write - index visible lpoints */
    int             *n;        /* Read Write - # of visible lpoints */
    pfVec3          *coords2D; /* Read Write - screen space X,Y,Z */
    float           *intensity;/* Write Only - resulting intensity */
    float           **focus;   /* Write Only - optional (de)focus */
    float           **drawTime;/* Write Only - optional drawTime */} pfCalligData;
} pfRasterData;

geoset is the pfGeoSet that is currently preprocessed. lpstate is the pfLPointState applied to that pfGeoSet. userData is the same as the data provided when declaring the callback.

index is a preallocated vector that points to light points that are visible. Even in a PRE callback the light points are projected on the screen before the user callback is called; the points outside of the screen are not in the index vector. See the pfLPointState man page on how to use the index vector in a callback.

n is a pointer to the number of elements in the index vector.

coords2D contains the coordinates of the light points on the screen, including the Z coordinates in screen space. The original coordinates can be accessed through the pfGeoSet. It is valid to change the values in coord2D in the callback, for example, to align the points on a grid.

intensity is a pre-allocated vector that contains the intensity of individual light points. A PRE callback must compute intensity.

focus is a NULL pointer. It is possible to provide an individual focus value for each point by doing the following:

You should not allocate an array in real-time; instead, allocate temporary memory beforehand and use userData to pass the memory address to the callback.

drawTime is a NULL pointer. With it you can provide an array of floats that give a draw time for each light point.

Before calling pfLPoint() in the light point process callback function, you can change the parameters in a pfCalligraphic object on a frame-by-frame basis, as shown in Example 21-3.

myLPointFunc(pfChannel *chan, void *data)
{
pfCalligraphic *calligraphic = pfGetCurCallig();
 
    if (calligraphic != NULL)
    {
        pfCalligFilterSize(calligraphic,FilterSizeX,FilterSizeY);
        pfCalligDefocus(calligraphic,Defocus);
        pfCalligRasterDefocus(calligraphic,rasterDefocus);
        pfCalligDrawTime(calligraphic, DrawTime);
        pfCalligStress(calligraphic, Stress)
   }
    pfLPoint();
}

FillterSizeX and FilterSizeY set the debunching distances along each axis. A filter size of 0 disables the debunching along that axis. Debunching can also be disabled on the pfLPointState. For more information about debunching, see “Debunching”.

Defocus sets the defocus applied to all calligraphic light points, unless a callback function returns a defocus array. In that case, each light point has a callback defocus value regardless of the one set on the pfCalligraphic object.

In a raster-plus-calligraphic video mode, a calligraphic system usually has the capability to apply a global defocus to the raster image, which is specified by the rasterDefocus parameter passed to the projector. This parameter affects the entire image, not just the raster light points.

For more information about defocus, see “Defocussing Calligraphic Objects”.

DrawTime is the time, in nano seconds, in which all calligraphic light points must be drawn, unless a callback returns a DrawTime array, which controls individual draw times. The overall effect of changing the draw time is to reduce or increase the intensity of all calligraphic light points.

The Stress value is compared against the significance value of a pfLPointState to determine whether the light points are displayed as calligraphic or raster. The Stress value should be as stable as possible to avoid having points going from raster to calligraphic or from calligraphic to raster each frame. For more information about stress, see “Significance”.

If there is not enough time to draw all of the calligraphic light points, some calligraphic light points can either not be drawn or, instead, drawn as raster light points, depending on the stress value of the calligraphic light point, described in “Frame to Frame Control”, and the significance value of the pfLPointState.

The stress value of a calligraphic light point is compared against the significance value of the pfLPointState. If the significance is greater or equal than the stress, the light is rendered as a calligraphic; otherwise, the light is rendered as a raster light.

To set the significance, use pfLPStateVal(lpstate, PFLPS_SIGNIFICANCE, significance).

Debunching eliminates some calligraphic points when they occur close together on the display system. Bunched calligraphic light points can create a heap effect, or worse, burn the display system where there is a group of calligraphic light points.

The debunching distances are set in pfCalligraphic on the X and Y axis, as described in “Frame to Frame Control”.

If two points in a pfGeoSet are within the debunching distance, the point with the lowest intensity is not rendered.

If you do not want a pfLPointState to be affected by debunching, you can disable it using pfLPStateMode() with the PFLPS_DEBUNCHING_MODE_OFF mode; PFLPS_DEBUNCHING_MODE_ON, the default, enables debunching.

Defocussing a calligraphic light point is often done to produce a specific lighting effect, for example, to simulate rainy conditions, light points should appear defocussed. The defocus is set within pfCalligraphic (see “Frame to Frame Control”) for all light points for one Frame, but it is possible to clamp the defocussing values by setting a min_defocus and a max_defocus value in the pfLPState using the following methods:

pfLPStateVal(lpstate,PFLPS_MIN_DEFOCUS, min_defocus);
pfLPStateVal(lpstate, PFLPS_MAX_DEFOCUS, max_defocus);

The SwapReady signal should always occur after a VME Swap signal. If this does not happen, the light point board starts a TooLate timer and two things may happen:

The LPB needs some time before it can accept new information from the VME, and the VISI bus needs some time after it has received the corresponding swap command. pfWaitForVmeBus() and pfWaitForVisiBus() allow the application to wait for the board to get ready before sending it new information.

The light point process is the same whether the light points are raster or calligraphic. The only difference is that, with calligraphic light points, pfCalligraphic has to be selected before calling pfPreprocessDList, which is done automatically by pfChannel.

pfSelectCalligraphic() selects the channel and LPB board to which the calligraphic light points are sent. pfGetCurCalligraphic() returns the current value set by pfSelectCalligraphic().