---

Forum » » Création-Développement » » Composite POC

---

Posté : 30-10-2012 09:48

NAME
CompositeTagList - Compose one bitmap onto another (V53)

SYNOPSIS
uint32 CompositeTagList(uint32 operator, struct BitMap *Source,
struct BitMap *Dest, struct TagItem *tags);

uint32 CompositeTags(uint32 operator, struct BitMap *Source,
struct BitMap *Dest, ...);

FUNCTION
This function implements Porter/Duff image compositing. If possible,
the operation will be hardware accelerated.

The function composes the bitmap pointed to by Source onto the bitmap
pointed to by Dest, using the specified operator.

Color values in the bitmaps are pre-multiplied with the alpha values
(or left unmodified if no alpha is present) before composition. The
most common operator is COMPOSITE_Src_Over_Dest, which, if the
destination's alpha value is 1, performs a standard OpenGL-style
linear blend between the Source and Destination bitmaps based on the
source alpha values (i.e. a "transparent blit").

For the purpose of the operation, this is the order in which the
modifiers are applied:

- The source rectangle specifies a sub-portion of the source bitmap
that becomes the source operand. Note that ONLY the source
rectangle is used for this, i.e for all intent and purpose this
is equivalent to specifying a bitmap that only contains the pixels
in the source rectangle.

- The destination operand is ALWAYS the complete destination bitmap.
However, no pixel outside the destination rectangle is modified.
Likewise, the OffsetX and OffsetY values specify coordinates
relative to the top left pixel of the destination bitmap, NOT
the destination rectangle.

- The scale factors are applied after the source rectangle is "cut"
from the source bitmap. This enlarges or shrinks the source
operand to a new size, doubling or removing pixels as needed, and
possibly filtering them. For all intent and purpose this is
equivalent to providing a bitmap that contains a scaled (and
possibly filtered) image of the original source rectangle.

- After scaling, the resulting pixels are composed into the
destination bitmap one by one using the specified operator. As
mentioned previously, no pixel outside the destination bitmap's
destination rectangle are modified; the result of the compose
operation there is discarded (this process is commonly called
"clipping", although the term "sciscoring" is more adequate).

- Exactly the same method is used for any alpha mask specified.

Please refer to the SDK documentation and example code for a more
in-depth discussion of the function and Porter/Duff style image
composition in general.

INPUTS
operator - the Porter/Duff image composition operator. Please refer to
graphics/composite.h for a list of operators, and the SDK
documentation for their meaning.
Source - The source bitmap. The bitmap may or may not have an Alpha
channel. If it hasn't got one, then an alpha of one is assumed.
The tag items may influence the interpretation of the alpha channel
as well. The bitmap must be BMF_DISPLAYABLE to be able to use
hardware acceleration, and it must be a compatible format, otherwise
software blending is used.
Dest - The destination bitmap. The same restrictions apply as with the
Source bitmap.
tags - A tag list with additional parameters.
Some of the tag items accept fix point real numbers. These are
32 bit integers with the upper 16 bit representing the decimal
part of the number, and the lower 16 bits representing the
fractional part. To convert from a float to a fixpoint number,
simply multiply 0x00010000 by the floating point number and
typecast the result to an int32.
Currently, the following tag items are possible:

COMPTAG_SrcX (uint32)

The X coordinate of a subrectangle on the source
bitmap. If a subrectangle is specified, only that part of the
bitmap is used for the compositing operation. Default is 0.

COMPTAG_SrcY (uint32)

The Y coordinate of a subrectangle on the source
bitmap. If a subrectangle is specified, only that part of the
bitmap is used for the compositing operation. Default is 0.

COMPTAG_SrcWidth (uint32)

The width of a subrectangle on the source
bitmap. If a subrectangle is specified, only that part of the
bitmap is used for the compositing operation. Default is the
width of the source bitmap.

COMPTAG_SrcHeight (uint32)

The height of a subrectangle on the source
bitmap. If a subrectangle is specified, only that part of the
bitmap is used for the compositing operation. Default is the
height of the source bitmap.

COMPTAG_DestX (uint32)

The X coordinate of a subrectangle on the
destination bitmap. This rectangle specifies the area of the
bitmap that is affected by the operation. In no case are pixels
outside of this area affected by the operation. Default is 0.

COMPTAG_DestY (uint32)

The Y coordinate of a subrectangle on the
destination bitmap. This rectangle specifies the area of the
bitmap that is affected by the operation. In no case are pixels
outside of this area affected by the operation. Default is 0.

COMPTAG_DestWidth (uint32)

The width of a subrectangle on the
destination bitmap. This rectangle specifies the area of the
bitmap that is affected by the operation. In no case are pixels
outside of this area affected by the operation. Default is the
width of the destination bitmap.

COMPTAG_DestHeight (uint32)

The height of a subrectangle on the
destination bitmap. This rectangle specifies the area of the
bitmap that is affected by the operation. In no case are pixels
outside of this area affected by the operation. Default is the
height of the destination bitmap.

COMPTAG_SrcAlpha (fixpoint)

A constant alpha factor for the source bitmap.
If the COMPFLAG_SrcAlphaOverride flag is given (see below) this
value replaces any alpha channel or mask that may be present in
the bitmap itself or specified via a tag item. If the
COMPFLAG_SrcAlphaOverride flag is not given, then the alpha
channel of the source bitmap is multiplied with this value. This
tag can be used to implement the Porter/Duff fade and darken
operators. The default value is 1.0. Setting any value outside
the interval of zero to one inclusive yields undefined results.

COMPTAG_DestAlpha (fixpoint)

A constant alpha factor for the destination bitmap.
If the COMPFLAG_DestAlphaOverride flag is given (see below) this
value replaces any alpha channel or mask that may be present in
the bitmap itself or specified via a tag item. If the
COMPFLAG_DestAlphaOverride flag is not given, then the alpha
channel of the source bitmap is multiplied with this value. This
tag can be used to implement the Porter/Duff fade and darken
operators. The default value is 1.0f. Setting any value outside
the interval of zero to one inclusive yields undefined results.

COMPTAG_ScaleX (fixpoint)

A floating-point scale factor by which the source bitmap resp.
the subrectangle of the source bitmap should be scaled
horizontally before the operation is executed. A value of 1.0f
means no scaling. Values greater than one enlarge the bitmap,
while values between zero and one shrink it. Values less than
or equal to zero are illegal and will result in the function to
fail. Defaults to 1.0f (no scaling)

COMPTAG_ScaleY (fixpoint)

A floating-point scale factor by which the source bitmap resp.
the subrectangle of the source bitmap should be scaled
vertically before the operation is executed. A value of 1.0f
means no scaling. Values greater than one enlarge the bitmap,
while values between zero and one shrink it. Values less than
or equal to zero are illegal and will result in the function to
fail. Defaults to 1.0f (no scaling)

COMPTAG_SrcAlphaMask (struct BitMap *)

A pointer to an (alternative) alpha channel for the source
bitmap. If specified, alpha information in the source bitmap
is ignored.

COMPTAG_DestAlphaMask (struct BitMap *)

A pointer to an (alternative) alpha channel for the destination
bitmap. If specified, alpha information in the destination
is ignored.

COMPTAG_SrcAlphaX (uint32)
COMPTAG_SrcAlphaY (uint32)

The X and Y coordinates of a subrectangle on the alpha channel
bitmap for the source. The width and height of the rectangle
are the same as the COMPTAG_SrcWidth and COMPTAG_SrcHeight.
Defaults to zero.

COMPTAG_DestAlphaX (uint32)
COMPTAG_DestAlphaY (uint32)

The X and Y coordinates of a subrectangle on the alpha channel
bitmap for the destination. The width and height of the
rectangle are the same as the COMPTAG_SrcWidth and
COMPTAG_SrcHeight.
Defaults to zero.

COMPTAG_Flags (uint32)

A bit mask specifying a number of flag bits that further modify
the operation of this call. Currently, the following flags are
defined:

COMPFLAG_SrcAlphaOverride
COMPFLAG_DestAlphaOverride
If either is set, the source respectively destination
alpha factor specified with COMPTAG_SrcAlpha resp.
COMPTAG_DestAlpha overrides the alpha value in the
bitmap or alpha mask, i.e. the alpha channel is assumed
to be a constant value as specified. If the respective
bit is not set, source resp. destination alpha channel
values are multiplied with the value specified by the
COMPTAG_SrcAlpha/COMPTAG_DestAlpha tag.

COMPFLAG_SrcFilter
If set, then bilinear filtering is applied to the
source bitmap to smooth out any artifacts introduced
by scaling. Filtering will have a slight but negligible
performance impact on hardware acceleration (usually
this will be so small it cannot be noticed), but might
have a severe impact when using software. The software
implementation may ignore this flag.

COMPFLAG_HardwareOnly
If this flag is set and the operation cannot be
performed in hardware, instead of falling back to
software the operation will fail entirely.*

COMPFLAG_IgnoreDestAlpha
If this flag is set, the destination bitmap is assumed
to be without alpha channel, i.e. Alpha is assumed to
be one. On some hardware this greatly enhances the
performance or reduces the overhead of the function
(for example, it frees the R200 driver from allocating
temporary texture storage). Use this flag whenever
possible.

COMPTAG_OffsetX (int32)
COMPTAG_OffsetY (int32)

Specifies the offset on the destination bitmap (NOT the
destination rectangle) where the source operand should be
applied. Negative coordinates are possible. By default, both
tags are zero.



RESULT
The function returns a status code. The following values are possible:

COMPERR_Success
No error. The operation performed successfully.

COMPERR_Incompatible
The input bitmaps were incompatible for the call. This usually
happens when a bitmap color format is not supported.

COMPERR_Value
An input value was illegal. This error is raised if e.g. the
specified operator is not known, or negative coordinates are
given, etc.

COMPERR_SoftwareFallback
The COMPFLAG_HardwareOnly flag was set but the operation was
incompatible with the current hardware.

COMPERR_OutOfMemory
Temporary storage was required to finish the operation but could
not be allocated.

COMPERR_Generic
An unknown error has occurred.

SEE ALSO
SDK examples and documentation.

enum enPDOperator
{
COMPOSITE_Clear = 0,
COMPOSITE_Src = 1,
COMPOSITE_Dest = 2,
COMPOSITE_Src_Over_Dest = 3,
COMPOSITE_Dest_Over_Src = 4,
COMPOSITE_Src_In_Dest = 5,
COMPOSITE_Dest_In_Src = 6,
COMPOSITE_Src_Out_Dest = 7,
COMPOSITE_Dest_Out_Src = 8,
COMPOSITE_Src_Atop_Dest = 9,
COMPOSITE_Dest_Atop_Src = 10,
COMPOSITE_Src_Xor_Dest = 11,
COMPOSITE_Plus = 12,

COMPOSITE_NumOperators = 13
};

/* Tag items for the Composite call */
#define COMPTAG_Base TAG_USER

/* (uint32) X clip coordinate on source bitmap (defaults to 0) */
#define COMPTAG_SrcX (COMPTAG_Base + 0)

/* (uint32) Y clip coordinate on source bitmap (defaults to 0) */
#define COMPTAG_SrcY (COMPTAG_Base + 1)

/* (uint32) Width of clip rectangle on source (defaults to full width) */
#define COMPTAG_SrcWidth (COMPTAG_Base + 2)

/* (uint32) Height of clip rectangle on source (defaults to full height) */
#define COMPTAG_SrcHeight (COMPTAG_Base + 3)

/* (uint32) X clip coordinate on dest bitmap (defaults to 0) */
#define COMPTAG_DestX (COMPTAG_Base + 4)

/* (uint32) Y clip coordinate on dest bitmap (defaults to 0) */
#define COMPTAG_DestY (COMPTAG_Base + 5)

/* (uint32) Width of clip rectangle on dest (defaults to full width) */
#define COMPTAG_DestWidth (COMPTAG_Base + 6)

/* (uint32) Height of clip rectangle on dest (defaults to full height) */
#define COMPTAG_DestHeight (COMPTAG_Base + 7)

/* (fixpoint) (additional) Alpha for source bitmap (no default) */
#define COMPTAG_SrcAlpha (COMPTAG_Base + 8)

/* (fixpoint) (additional) Alpha for destination bitmap (no default) */
#define COMPTAG_DestAlpha (COMPTAG_Base + 9)

/* (fixpoint) X scale factor for source bitmap (defaults to 1.0) */
#define COMPTAG_ScaleX (COMPTAG_Base + 10)

/* (fixpoint) Y scale factor for source bitmap (defaults to 1.0) */
#define COMPTAG_ScaleY (COMPTAG_Base + 11)

/* (struct Bitmap *) Alpha mask for source. Specifying this tag overrides any
* alpha that might be present in the source bitmap.
*/
#define COMPTAG_SrcAlphaMask (COMPTAG_Base + 12)

/* (struct Bitmap *) Alpha mask for the destination. Specifying this tag
* overrides any alpha that might be present in the destination bitmap.
*/
#define COMPTAG_DestAlphaMask (COMPTAG_Base + 13)

/* (uint32, see defines below) Specifies a set of flags that may modify the
* operation. See the defines below
*/
#define COMPTAG_Flags (COMPTAG_Base + 18)

/* (int32) X Coordinate on the destination bitmap that the operation should be
* applied to. Defaults to zero.
*/
#define COMPTAG_OffsetX (COMPTAG_Base + 20)

/* (int32) Y Coordinate on the destination bitmap that the operation should be
* applied to. Defaults to zero.
*/
#define COMPTAG_OffsetY (COMPTAG_Base + 21)

/* (struct BitMap *) when the source and/or destination bitmaps are located in
* main memory, this tag tells the graphics system to upload the bitmaps to
* the same board the friend bitmap is located on.
*/
#define COMPTAG_FriendBitMap (COMPTAG_Base + 22)

/* (uint32) the same as above, but a DisplayID is used as reference to the board
* and not a bitmap.
*/
#define COMPTAG_DisplayID (COMPTAG_Base + 23)

/* (uint32) the X/Y coordinates on the src alpha map to use for compositing. If not
* specified, use the same as the SrcX and SrcY
*/
#define COMPTAG_SrcAlphaX (COMPTAG_Base + 14)
#define COMPTAG_SrcAlphaY (COMPTAG_Base + 15)

/* (uint32) the X/Y coordinates on the destination alpha map to use. If not
* specified, use the DestX and DestY
*/
#define COMPTAG_DestAlphaX (COMPTAG_Base + 16)
#define COMPTAG_DestAlphaY (COMPTAG_Base + 17)

/*
* The following group of tag items deals with direct triangle mapping. Read the
* autodoc for a detailed explanation
*/
#define COMPTAG_VertexArray (COMPTAG_Base + 30)
#define COMPTAG_IndexArray (COMPTAG_Base + 31)
#define COMPTAG_VertexFormat (COMPTAG_Base + 32)
#define COMPTAG_NumTriangles (COMPTAG_Base + 33)

/*
* This group of tag items can be used to specify up to four colors, either
* as an 32 bit ARGB value, or as a set of discreet fixpoint numbers.
*
* The fixpoint numbers range is 0 to 1. Specifying a fixpoint component
* overrides the ARGB value completely.
*/
#define COMPTAG_Color0 (COMPTAG_Base + 40)
#define COMPTAG_Color1 (COMPTAG_Base + 41)
#define COMPTAG_Color2 (COMPTAG_Base + 42)
#define COMPTAG_Color3 (COMPTAG_Base + 43)

#define COMPTAG_Color0_Red (COMPTAG_Base + 44)
#define COMPTAG_Color0_Green (COMPTAG_Base + 45)
#define COMPTAG_Color0_Blue (COMPTAG_Base + 46)
#define COMPTAG_Color0_Alpha (COMPTAG_Base + 47)

#define COMPTAG_Color1_Red (COMPTAG_Base + 48)
#define COMPTAG_Color1_Green (COMPTAG_Base + 49)
#define COMPTAG_Color1_Blue (COMPTAG_Base + 50)
#define COMPTAG_Color1_Alpha (COMPTAG_Base + 51)

#define COMPTAG_Color2_Red (COMPTAG_Base + 52)
#define COMPTAG_Color2_Green (COMPTAG_Base + 53)
#define COMPTAG_Color2_Blue (COMPTAG_Base + 54)
#define COMPTAG_Color2_Alpha (COMPTAG_Base + 55)

#define COMPTAG_Color3_Red (COMPTAG_Base + 56)
#define COMPTAG_Color3_Green (COMPTAG_Base + 57)
#define COMPTAG_Color3_Blue (COMPTAG_Base + 58)
#define COMPTAG_Color3_Alpha (COMPTAG_Base + 59)


/*
* Reserved
*/
#define COMPTAG_Private (COMPTAG_Base + 34)
#define COMPTAG_Private2 (COMPTAG_Base + 35)

/* Vertex Array format flags */
#define COMPVF_STW0_Present 0x02
#define COMPVF_STW1_Present 0x04

/*
* Flags for the COMPTAG_Flags tag item
*
* Currently defined flags are:
* COMPFLAG_SrcAlphaOverride - If set, the value specified in SrcAlpha overrides
* the value in the source bitmap, which means that the source bitmap is
* assumed to have a constant alpha over the entire image. If not set,
* the SrcAlpha value is used to modulate/scale any other alpha channel.
* COMPFLAG_DestAlphaOverride - Like COMPFLAG_SrcAlphaOverride, for the
* destination bitmap.
* COMPFLAG_SrcFilter - If set, enables bilinear filtering of the source bitmap
* while scaling. While this can improve the quality of scaled images,
* it might cause a dramatic slowdown when the operation is emulated
* in software.
* COMPFLAG_DestFilter - Like COMPFLAG_SrcFilter for the destination bitmap.
* COMPFLAG_HardwareOnly - If set, the call will fail with an error code if
* the operation cannot be performed in hardware. Reasons for this !include!
* software-only bitmaps, unsupported color formats, etc.
* COMPFLAG_ForceSoftware - If set, the operation will be emulated in software
* even if it could be performed in hardware. This is mostly useful for
* testing purposes. Setting this overrides COMPFLAG_HardwareOnly.
* COMPFLAG_Color1Modulate - If set, then Color 1 is used as a modulate
* color for the src bitmap. That is, each color component of each pixel
* in the source bitmap is multiplied with the color 1 (including its
* alpha). All other effects stay in effect. This flag can essentially
* be used to "tint" a bitmap in the given color
*/

#define COMPFLAG_SrcAlphaOverride (1L << 0)
#define COMPFLAG_DestAlphaOverride (1L << 1)
#define COMPFLAG_SrcFilter (1L << 2)
#define COMPFLAG_HardwareOnly (1L << 3)
#define COMPFLAG_IgnoreDestAlpha (1L << 4)
#define COMPFLAG_ForceSoftware (1L << 7)
#define COMPFLAG_Color1Modulate (1L << 8)

/* Helper Macros to convert to/from fixpoint numbers */
#define COMP_FIX_ONE 0x00010000
#define COMP_FLOAT_TO_FIX(f) (int32)((float)COMP_FIX_ONE * f)
#define COMP_FIX_TO_FLOAT(fix) ((float)fix / (float)COMP_FIX_ONE)
#define COMP_FIX_TO_UINT32(fix) ((fix) / COMP_FIX_ONE)


/* Possible constants for Source */
#define COMPSRC_SOLIDCOLOR ((struct BitMap *)1)

enum enCompositeError
{
COMPERR_Success = 0,
COMPERR_Incompatible = 1, /* Incompatible bitmaps for operation */
COMPERR_Value = 2, /* An input value is out of range */
COMPERR_SoftwareFallback = 3, /* Operation would fall back to
software emulation and hardware
only was requested */
COMPERR_OutOfMemory = 4, /* The operation tried to allocate
memory but failed */
COMPERR_Generic = 5, /* Some generic error has occurred */
COMPERR_UnknownOperator = 6, /* Unknown operator specified */
COMPERR_MissingInput = 7, /* Missing a mandatory tag item */

};

---

Cet article provient de Le site des utilisateurs francophones actuels et futurs d'AmigaOS 4.x
https://amiga-ng.org/viewtopic.php?topic=1399&forum=14