'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved 
.TH mlib_ImageComposite 3MLIB "2 Mar 2007" "SunOS 5.11" "mediaLib Library Functions"
.SH NAME
mlib_ImageComposite \- image composition
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... \fB-lmlib\fR [ \fIlibrary\fR... ]
#include <mlib.h>

\fBmlib_status\fR \fBmlib_ImageComposite\fR(\fBmlib_image *\fR\fIdst\fR, \fBconst mlib_image *\fR\fIsrc1\fR,
     \fBconst mlib_image *\fR\fIsrc2\fR, \fBmlib_blend\fR \fIbsrc1\fR, \fBmlib_blend\fR \fIbsrc2\fR,
     \fBmlib_s32\fR \fIcmask\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBmlib_ImageComposite()\fR function supports digital image composition.
.sp
.LP
It is a wrapper of the \fBmlib_ImageBlend_BSCR1_BSRC2\fR group of functions and can perform various types of composition based on the parameters passed in, whereas each function in that group can perform only the one kind of composition denoted by its name.
.sp
.LP
The image type must be \fBMLIB_BYTE\fR. The input and output images must contain three or four channels. For three-channel images, the alpha value is as if the alpha value is 1.
.sp
.LP
The following are predefined blend factor types used in mediaLib image composition functions.
.sp
.in +2
.nf
/* image blend factors */
typedef enum {
    MLIB_BLEND_ZERO,
    MLIB_BLEND_ONE,
    MLIB_BLEND_DST_COLOR,
    MLIB_BLEND_SRC_COLOR,
    MLIB_BLEND_ONE_MINUS_DST_COLOR,
    MLIB_BLEND_ONE_MINUS_SRC_COLOR,
    MLIB_BLEND_DST_ALPHA,
    MLIB_BLEND_SRC_ALPHA,
    MLIB_BLEND_ONE_MINUS_DST_ALPHA,
    MLIB_BLEND_ONE_MINUS_SRC_ALPHA,
    MLIB_BLEND_SRC_ALPHA_SATURATE
} mlib_blend;
.fi
.in -2

.sp
.LP
See the following table for the definitions of the blend factors.
.sp

.sp
.TS
tab();
cw(2.97i) cw(1.85i) cw(.67i) 
lw(2.97i) lw(1.85i) lw(.67i) 
.
TypeBlend Factor [*]Abbr.
_
MLIB_BLEND_ZERO(0,0,0,0)ZERO
MLIB_BLEND_ONE(1,1,1,1)ONE
MLIB_BLEND_DST_COLOR(Rd,Gd,Bd,Ad)DC
MLIB_BLEND_SRC_COLOR(Rs,Gs,Bs,As)SC
MLIB_BLEND_ONE_MINUS_DST_COLOR(1,1,1,1)-(Rd,Gd,Bd,Ad)OMDC
MLIB_BLEND_ONE_MINUS_SRC_COLOR(1,1,1,1)-(Rs,Gs,Bs,As)OMSC
MLIB_BLEND_DST_ALPHA(Ad,Ad,Ad,Ad)DA
MLIB_BLEND_SRC_ALPHA(As,As,As,As)SA
MLIB_BLEND_ONE_MINUS_DST_ALPHA(1,1,1,1)-(Ad,Ad,Ad,Ad)OMDA
MLIB_BLEND_ONE_MINUS_SRC_ALPHA(1,1,1,1)-(As,As,As,As)OMSA
MLIB_BLEND_SRC_ALPHA_SATURATE(f,f,f,1)SAS
.TE

.sp
.LP
[*]: The components of the first source image pixel are \fB(Rd,Gd,Bd,Ad)\fR, and the components of the second source pixel are \fB(Rs,Gs,Bs,As)\fR. Function \fBf = min(As, 1-Ad)\fR.
.sp
.LP
The blending formula for non-in-place processing is:
.sp
.in +2
.nf
Cd = Cs1*S1 + Cs2*S2
.fi
.in -2

.sp
.LP
where \fBCd\fR is the destination pixel \fB(Rd,Gd,Bd,Ad)\fR, \fBCs1\fR is the first source pixel \fB(Rs1,Gs1,Bs1,As1)\fR, \fBCs2\fR is the second source pixel \fB(Rs2,Gs2,Bs2,As2)\fR, and \fBS1\fR and \fBS2\fR are the blend factors for the first and second sources, respectively.
.SH PARAMETERS
.sp
.LP
The function takes the following arguments:
.sp
.ne 2
.mk
.na
\fB\fIdst\fR\fR
.ad
.RS 9n
.rt  
Pointer to destination image.
.RE

.sp
.ne 2
.mk
.na
\fB\fIsrc1\fR\fR
.ad
.RS 9n
.rt  
Pointer to the first source image.
.RE

.sp
.ne 2
.mk
.na
\fB\fIsrc2\fR\fR
.ad
.RS 9n
.rt  
Pointer to the second source image.
.RE

.sp
.ne 2
.mk
.na
\fB\fIbsrc1\fR\fR
.ad
.RS 9n
.rt  
Blend factor type for the first source image.
.RE

.sp
.ne 2
.mk
.na
\fB\fIbsrc2\fR\fR
.ad
.RS 9n
.rt  
Blend factor type for the second source image.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcmask\fR\fR
.ad
.RS 9n
.rt  
Channel mask to indicate the alpha channel. Each bit of the mask represents a channel in the image. The channel corresponding to the 1 bit is the alpha channel. cmask must be either 0x01 or 0x08.
.RE

.SH RETURN VALUES
.sp
.LP
The function returns \fBMLIB_SUCCESS\fR if successful. Otherwise it returns \fBMLIB_FAILURE\fR.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBmlib_ImageBlend_BSRC1_BSRC2\fR(3MLIB), \fBmlib_ImageBlend_BSRC1_BSRC2_Inp\fR(3MLIB), \fBmlib_ImageComposite_Inp\fR(3MLIB), \fBattributes\fR(5)