mlib_ImageComposite(3mlib)

1mlib_ImageComposite(3MLIB)mediaLib Library Functionsmlib_ImageComposite(3MLIB)
2
3
4

NAME

6       mlib_ImageComposite - image composition
7

SYNOPSIS

9       cc [ flag... ] file... -lmlib [ library... ]
10       #include <mlib.h>
11
12       mlib_status mlib_ImageComposite(mlib_image *dst, const mlib_image *src1,
13            const mlib_image *src2, mlib_blend bsrc1, mlib_blend bsrc2,
14            mlib_s32 cmask);
15
16

DESCRIPTION

18       The mlib_ImageComposite() function supports digital image composition.
19
20
21       It  is  a wrapper of the mlib_ImageBlend_BSCR1_BSRC2 group of functions
22       and can perform various types of composition based  on  the  parameters
23       passed in, whereas each function in that group can perform only the one
24       kind of composition denoted by its name.
25
26
27       The image type must be MLIB_BYTE. The input and output images must con‐
28       tain  three or four channels. For three-channel images, the alpha value
29       is as if the alpha value is 1.
30
31
32       The following are predefined blend factor types used in mediaLib  image
33       composition functions.
34
35         /* image blend factors */
36         typedef enum {
37             MLIB_BLEND_ZERO,
38             MLIB_BLEND_ONE,
39             MLIB_BLEND_DST_COLOR,
40             MLIB_BLEND_SRC_COLOR,
41             MLIB_BLEND_ONE_MINUS_DST_COLOR,
42             MLIB_BLEND_ONE_MINUS_SRC_COLOR,
43             MLIB_BLEND_DST_ALPHA,
44             MLIB_BLEND_SRC_ALPHA,
45             MLIB_BLEND_ONE_MINUS_DST_ALPHA,
46             MLIB_BLEND_ONE_MINUS_SRC_ALPHA,
47             MLIB_BLEND_SRC_ALPHA_SATURATE
48         } mlib_blend;
49
50
51
52       See the following table for the definitions of the blend factors.
53
54
55
56
57                    Type                   Blend Factor [*]        Abbr.
58       ───────────────────────────────────────────────────────────────────
59       MLIB_BLEND_ZERO                  (0,0,0,0)                 ZERO
60       MLIB_BLEND_ONE                   (1,1,1,1)                 ONE
61       MLIB_BLEND_DST_COLOR             (Rd,Gd,Bd,Ad)             DC
62       MLIB_BLEND_SRC_COLOR             (Rs,Gs,Bs,As)             SC
63       MLIB_BLEND_ONE_MINUS_DST_COLOR   (1,1,1,1)-(Rd,Gd,Bd,Ad)   OMDC
64       MLIB_BLEND_ONE_MINUS_SRC_COLOR   (1,1,1,1)-(Rs,Gs,Bs,As)   OMSC
65       MLIB_BLEND_DST_ALPHA             (Ad,Ad,Ad,Ad)             DA
66
67       MLIB_BLEND_SRC_ALPHA             (As,As,As,As)             SA
68       MLIB_BLEND_ONE_MINUS_DST_ALPHA   (1,1,1,1)-(Ad,Ad,Ad,Ad)   OMDA
69       MLIB_BLEND_ONE_MINUS_SRC_ALPHA   (1,1,1,1)-(As,As,As,As)   OMSA
70       MLIB_BLEND_SRC_ALPHA_SATURATE    (f,f,f,1)                 SAS
71
72
73
74       [*]:  The components of the first source image pixel are (Rd,Gd,Bd,Ad),
75       and the components of the second source pixel are (Rs,Gs,Bs,As).  Func‐
76       tion f = min(As, 1-Ad).
77
78
79       The blending formula for non-in-place processing is:
80
81         Cd = Cs1*S1 + Cs2*S2
82
83
84
85       where  Cd  is  the  destination  pixel  (Rd,Gd,Bd,Ad), Cs1 is the first
86       source  pixel  (Rs1,Gs1,Bs1,As1),  Cs2  is  the  second  source   pixel
87       (Rs2,Gs2,Bs2,As2),  and  S1  and S2 are the blend factors for the first
88       and second sources, respectively.
89

PARAMETERS

91       The function takes the following arguments:
92
93       dst      Pointer to destination image.
94
95
96       src1     Pointer to the first source image.
97
98
99       src2     Pointer to the second source image.
100
101
102       bsrc1    Blend factor type for the first source image.
103
104
105       bsrc2    Blend factor type for the second source image.
106
107
108       cmask    Channel mask to indicate the alpha channel. Each  bit  of  the
109                mask  represents  a  channel  in the image. The channel corre‐
110                sponding to the 1 bit is the  alpha  channel.  cmask  must  be
111                either 0x01 or 0x08.
112
113

RETURN VALUES

115       The  function  returns MLIB_SUCCESS if successful. Otherwise it returns
116       MLIB_FAILURE.
117

ATTRIBUTES

119       See attributes(5) for descriptions of the following attributes:
120
121
122
123
124       ┌─────────────────────────────┬─────────────────────────────┐
125       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
126       ├─────────────────────────────┼─────────────────────────────┤
127       │Interface Stability          │Committed                    │
128       ├─────────────────────────────┼─────────────────────────────┤
129       │MT-Level                     │MT-Safe                      │
130       └─────────────────────────────┴─────────────────────────────┘
131

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUES

ATTRIBUTES

SEE ALSO