intrinsic-173 Set3DObjectAlpha

173: Set3DObjectAlpha(Handle, Enable, DepthCheck, BackBlend, Flags, Trans);

This intrinsic sets the Alpha or Transparency parameters of an object. Objects can be set to any level of transparency ranging from totally opaque to totally transparent. The intrinsic also lets you control the way in which the colors of transparent objects are blended with objects behind it or the background.

Arguments:

Handle. This argument is an integer handle created by the Add3DObject intrinsic. The handle must be for a Mesh.

Enable. This argument is an integer Boolean which enables or disables the transparency effect.

DepthCheck. This argument is an integer Boolean which enables or disable depth checking. When depth checking is enabled, the program compares the depth of objects in the scene when applying transparency. This controls which object is drawn on top of which other object, and makes objects underneath transparent objects to appear dimmer than the top object. The feature is only useful for scenes where there is more than one object. If there is only one object, the feature is superfluous and can be turned off for a slight speed improvement.

BackBlend. This argument is an integer Boolean which enables or disable background blending. When background blending is enabled, the colors of the foreground and background objects are blended to give realistic combined colors.

Flags. This argument is an integer that lets you create custom, user-controlled alpha blending. The blending works by combining the Source and Destination colors. The Destination is  the location where a new pixels is about to be drawn. The Source is the new pixel that is about to be drawn. The colors Source and Destination pixels are combined using the following equation:

Result = Source * Source Mode <Operator> Destination * Destination Mode

This process is done separately on the Red, Green, Blue and Alpha components of the Source and Destination value. Values are truncated to a maximum value of 255.

The details of the equation are specified by the values in the flag. The flag is divided into four parts, each of which takes up one byte or eight bits of the integer. The assignment of each byte is illustrated by the following diagram:

UUUUUUUU EEEEEEEE SSSSSSSS DDDDDDDD

U = Enable/Disable

E = Operator

S = Source Blending mode

D = Destination Blending mode.

The high byte is treated as a Boolean that enables or disables User Blending. The next byte specifies Operator. The next byte controls the Source blending mode. The bottom byte controls the Destination blending mode. The following chart illustrates how each byte in the Flags variable is used:

Operator. The Operator value specifies five operators that can be applied to the equation specified above:

0 = Add

1 = Subtract

2 = Reverse Subtract

3 = Minimum of the two values

4 = Maximum of the two values

Source Blending Mode. These modes control the way a source pixel is modified in the equation shown above:

0 = Multiply each RGBA color component by 0, making them black.

1 = Multiply each RGBA color component by 1, making the value unchanged.

2 = Multiply the Source color components by the normalized Destination color components.

3 = Multiply the Source color by the normalized Destination color components, then subtract from 1.

4 = Multiply the Source color components by the Source Alpha.

5 = Multiply the Source color components Destination the Source Alpha, then subtract from 1.

6 = Multiply the Source color components by the Source Alpha.

7 = Multiply the Source color components by the Destination Alpha, then subtract from 1.

8 = Multiply the Destination color components by the minimum of the Source Alpha and 1 minus the Destination Alpha.

Destination Blending Mode. These modes control the way the Destination pixel is modified in the equation shown above:

0 = Multiply each RGBA color component by 0, making them black.

1 = Multiply each RGBA color component by 1, making the value unchanged.

2 = Multiply the Destination color components by the normalized Source color components.

3 = Multiply the Destination color components by the normalized Source color components, then subtract from 1.

4 = Multiply the Destination color components by the Source Alpha.

5 = Multiply the Destination color components by the Source Alpha, then subtract from 1.

6 = Multiply the Destination color components by the Destination Alpha.

7 = Multiply the Destination color components by the Destination Alpha, then subtract from 1.

Trans. This is a real value that sets the transparency of the specified object in a range of 0 to 100. Zero is opaque and 100 is completely transparent.