Set or get the foreground, background default values and flags of a buffer
Name
ggiBufSetGCForeground, ggiBufSetGCBackground, ggiBufSetGCFlags, ggiBufGetGCForeground, ggiBufGetGCBackground, ggiBufGetGCFlags : Set or get the foreground, background default values and flags of a buffer
Synopsis
#include <ggi/buf.h> int ggiBufSetGCForeground(ggiBuf_t buf, ggi_bufval val); int ggiBufSetGCBackground(ggiBuf_t buf, ggi_bufval val); int ggiBufSetGCFlags(ggiBuf_t buf, enum ggiBuf_flags flags); int ggiBufGetGCForeground(ggiBuf_t buf, ggi_bufval *val); int ggiBufGetGCBackground(ggiBuf_t buf, ggi_bufval *val); int ggiBufGetGCFlags(ggiBuf_t buf, enum ggiBuf_flags *flags);
Description
ggiBufSetGCForeground and ggiBufGetGCForeground set and read, respectively, the current value used as a default for the channel (Alpha, Z, etc.) represented by the buffer buf when data is sent to a compound buffer or clad visual to which buf belongs, when such data has no corresponding channel. This value applies to all pixels drawn in the foreground color in two-color operations, or otherwise to all pixels.
ggiBufSetGCBackground and ggiBufGetGCBackground set and read, respectively, the current value used as a default when the buffer is cleared with ggiBufClear. This value is also used in the same way that the foreground value is used when a two-color operation like text drawing is performed, but applies only to pixels drawn in the background color.
ggiBufSetGCFlags and ggiBufGetGCFlags set and read, respectively, flags which define the default behavior of the buffer.
The following flag values are defined for both Alpha and Z buffers:
- BUF_DISPOSE
Designates that the resultant alpha or Z value is not to overwrite the destination alpha or Z value, and is instead thrown away.
- BUF_PUTGET
Designates that the channel is valid as both source and destination when a command is invoked which causes data from the buffer to be written back to itself at another position. In other words, on a clad visual, when this flag is not set, the copybox operation will use the buffer's foreground value for the source value, whereas, when it is set, the values in the buffer at the source location will be used. (This also works for crossblt, when the clad visual is used as the source visual.) Note that this also affects LibGGI get/put operations when used on a clad visual that contains alpha or Z in-pixel channels, however, using it as such must only be done when it is known that the channels are in-pixel, because otherwise it has no affect on get/put operations.
The following flag values are defined for Z buffers:
- BUF_CMP_GT, BUF_CMP_LT, BUF_CMP_EQ, BUF_CMP_GTE, BUF_CMP_LTE
These flags determine the comparison type (greater than, less than, greater than or equal, and less than or equal, respectively) used when deciding which of two Z values is considered to be over the other. BUF_CMP_LTE is the default comparison (assuming it is available), meaning that if the source Z value is less than or equal to the destination Z value, the pixel in question will be drawn.
The following flags are defined for Alpha buffers and determine the type of blend performed:
- BUF_BLEND_OVER or BUF_BLEND_SRC_OVER`
Values are blended using the following rule expressed with normalized Alpha values:
D = As * S + (1 - As) * D * Ad; A = As + (1 - As) * Ad
- BUF_BLEND_UNDER or BUF_BLEND_DST_OVER
Values are blended using the following rule expressed with normalized Alpha values:
D = Ad * D + (1 - Ad) * S * As; A = Ad + (1 - Ad) * As
- BUF_BLEND_SRC_IN
Values are blended using the following rule expressed with normalized Alpha values:
D = As * S * Ad; A = As * Ad
- BUF_BLEND_DST_IN
Values are blended using the following rule expressed with normalized Alpha values:
D = Ad * D * As; A = Ad * As
- BUF_BLEND_SRC_OUT
Values are blended using the following rule expressed with normalized Alpha values:
D = As * S * (1 - Ad); A = As * (1 - Ad)
- BUF_BLEND_DST_OUT
Values are blended using the following rule expressed with normalized Alpha values:
D = Ad * D * (1 - As); A = Ad * (1 - As)
- BUF_BLEND_TOP or BUF_BLEND_SRC_TOP
Values are blended using the following rule expressed with normalized Alpha values:
D = As * S * Ad + (1 - As) * D * Ad; A = As * Ad + (1 - As) * Ad
- BUF_BLEND_BOTTOM or BUF_BLEND_DST_TOP
Values are blended using the following rule expressed with normalized Alpha values:
D = Ad * D * As + (1 - Ad) * S * As; A = Ad * As + (1 - Ad) * As
- BUF_BLEND_XOR
Values are blended using the following rule expressed with normalized Alpha values:
D = As * S * (1-Ad) + (1-As) * D * Ad; A = As * (1-Ad) + (1-As) * Ad
- BUF_BLEND_PLUS
Values are blended using the following rule expressed with normalized Alpha values:
D = As * S + Ad * D; A = As * Ad
- BUF_BLEND_ALT
This nifty feature allows you to choose a second blend to be used in when both alpha and Z are in use, which will be used when the Z value of the source is determined to be behind that of the destination. To choose the second blend, shift any of the below BUF_BLEND* flags (with the exception of BUF_BLEND_*_PREMULT) left by BUF_ALTBLEND_SHIFT bits. In order to use this feature, this flag must have been set on both the Z and the Alpha buffer when they were first created. This flag should not be shifted by BUF_ALTBLEND_SHIFT, as it obviously applies to both blends.
- BUF_BLEND_SRC_PREMULT
Values in the source are premultiplied by their Alpha. This flag should not be shifted by BUF_ALTBLEND_SHIFT, as it applies to both the primary and secondary blend.
- BUF_BLEND_DST_PREMULT
Values in the destination are premultiplied by their Alpha. This flag should not be shifted by BUF_ALTBLEND_SHIFT, as it applies to both the primary and secondary blend.
- BUF_BLEND_POSTDIV
The values obtained from the above formulas are divided by the resultant Alpha. This is generally desired for OVER/UNDER/XOR/PLUS blends, and generally not desired for the IN/OUT blends.
Return value
All four functions 0 for OK or a negative value on failure. In the case of ggiSetGCFlags, failures usually mean that the display does not support the desired blend or comparison. You can avoid such failures by insisting that the blend be available when the buffer is created with ggiBufAddAlpha/ggiBufCreateAlpha(3) or ggiBufAddZ/ggiBufCreateZ(3).