# lv_draw_sw_mask.h (/api/draw/sw/lv_draw_sw_mask_h)



<RelatedHeaders name="lv_draw_sw_mask_private.h" isPrivate="false" />

<ApiSummary functions="10" enums="3" typedefs="1" macros="2" />

Functions [#functions]

<ApiMember kind="function" name="lv_draw_sw_mask_init" file="draw/sw/lv_draw_sw_mask.h" line="71" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L71">
  lv_draw_sw_mask_init [#lv_draw_sw_mask_init]

  ```c title=" " lineNumbers=1
  void lv_draw_sw_mask_init(void)
  ```
</ApiMember>

<ApiMember kind="function" name="lv_draw_sw_mask_deinit" file="draw/sw/lv_draw_sw_mask.h" line="73" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L73">
  lv_draw_sw_mask_deinit [#lv_draw_sw_mask_deinit]

  ```c title=" " lineNumbers=1
  void lv_draw_sw_mask_deinit(void)
  ```
</ApiMember>

<ApiMember kind="function" name="lv_draw_sw_mask_apply" file="draw/sw/lv_draw_sw_mask.h" line="87" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L87">
  lv_draw_sw_mask_apply [#lv_draw_sw_mask_apply]

  Apply the added buffers on a line. Used internally by the library's drawing routines.

  ```c title=" " lineNumbers=1
  lv_draw_sw_mask_res_t lv_draw_sw_mask_apply(void *masks[], lv_opa_t *mask_buf, int32_t abs_x, int32_t abs_y, int32_t len)
  ```

  <span className="sr-only">
    Parameters
  </span>

  | Name       | Type                                             | Description                                                                               |
  | ---------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
  | `masks`    | `void *`                                         | the masks list to apply, must be ended with NULL pointer in array.                        |
  | `mask_buf` | <ApiLink name="lv_opa_t" display="lv_opa_t *" /> | store the result mask here. Has to be `len` byte long. Should be initialized with `0xFF`. |
  | `abs_x`    | <ApiLink name="int32_t" />                       | absolute X coordinate where the line to calculate start                                   |
  | `abs_y`    | <ApiLink name="int32_t" />                       | absolute Y coordinate where the line to calculate start                                   |
  | `len`      | <ApiLink name="int32_t" />                       | length of the line to calculate (in pixel count)                                          |

  **Returns:** <ApiLink name="lv_draw_sw_mask_res_t" /> — One of these values:

  * `LV_DRAW_MASK_RES_FULL_TRANSP`: the whole line is transparent. `mask_buf` is not set to zero
  * `LV_DRAW_MASK_RES_FULL_COVER`: the whole line is fully visible. `mask_buf` is unchanged
  * `LV_DRAW_MASK_RES_CHANGED`: `mask_buf` has changed, it shows the desired opacity of each pixel in the given line
</ApiMember>

<ApiMember kind="function" name="lv_draw_sw_mask_free_param" file="draw/sw/lv_draw_sw_mask.h" line="99" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L99">
  lv_draw_sw_mask_free_param [#lv_draw_sw_mask_free_param]

  Free the data from the parameter. It's called inside `lv_draw_sw_mask_remove_id` and `lv_draw_sw_mask_remove_custom` Needs to be called only in special cases when the mask is not added by `lv_draw_mask_add` and not removed by `lv_draw_mask_remove_id` or `lv_draw_mask_remove_custom`

  ```c title=" " lineNumbers=1
  void lv_draw_sw_mask_free_param(void *p)
  ```

  <span className="sr-only">
    Parameters
  </span>

  | Name | Type     | Description                 |
  | ---- | -------- | --------------------------- |
  | `p`  | `void *` | pointer to a mask parameter |
</ApiMember>

<ApiMember kind="function" name="lv_draw_sw_mask_line_points_init" file="draw/sw/lv_draw_sw_mask.h" line="112" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L112">
  lv_draw_sw_mask_line_points_init [#lv_draw_sw_mask_line_points_init]

  Initialize a line mask from two points.

  ```c title=" " lineNumbers=1
  void lv_draw_sw_mask_line_points_init(lv_draw_sw_mask_line_param_t *param, int32_t p1x, int32_t p1y, int32_t p2x, int32_t p2y, lv_draw_sw_mask_line_side_t side)
  ```

  <span className="sr-only">
    Parameters
  </span>

  | Name    | Type                                                                                     | Description                                                                                                                                                                                                                               |
  | ------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `param` | <ApiLink name="lv_draw_sw_mask_line_param_t" display="lv_draw_sw_mask_line_param_t *" /> | pointer to a `lv_draw_mask_param_t` to initialize                                                                                                                                                                                         |
  | `p1x`   | <ApiLink name="int32_t" />                                                               | X coordinate of the first point of the line                                                                                                                                                                                               |
  | `p1y`   | <ApiLink name="int32_t" />                                                               | Y coordinate of the first point of the line                                                                                                                                                                                               |
  | `p2x`   | <ApiLink name="int32_t" />                                                               | X coordinate of the second point of the line                                                                                                                                                                                              |
  | `p2y`   | <ApiLink name="int32_t" />                                                               | y coordinate of the second point of the line                                                                                                                                                                                              |
  | `side`  | <ApiLink name="lv_draw_sw_mask_line_side_t" />                                           | and element of `lv_draw_mask_line_side_t` to describe which side to keep. With `LV_DRAW_MASK_LINE_SIDE_LEFT/RIGHT` and horizontal line all pixels are kept With `LV_DRAW_MASK_LINE_SIDE_TOP/BOTTOM` and vertical line all pixels are kept |
</ApiMember>

<ApiMember kind="function" name="lv_draw_sw_mask_line_angle_init" file="draw/sw/lv_draw_sw_mask.h" line="126" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L126">
  lv_draw_sw_mask_line_angle_init [#lv_draw_sw_mask_line_angle_init]

  Initialize a line mask from a point and an angle.

  ```c title=" " lineNumbers=1
  void lv_draw_sw_mask_line_angle_init(lv_draw_sw_mask_line_param_t *param, int32_t px, int32_t py, int16_t angle, lv_draw_sw_mask_line_side_t side)
  ```

  <span className="sr-only">
    Parameters
  </span>

  | Name    | Type                                                                                     | Description                                                                                                                                                                                                                              |
  | ------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `param` | <ApiLink name="lv_draw_sw_mask_line_param_t" display="lv_draw_sw_mask_line_param_t *" /> | pointer to a `lv_draw_mask_param_t` to initialize                                                                                                                                                                                        |
  | `px`    | <ApiLink name="int32_t" />                                                               | X coordinate of a point of the line                                                                                                                                                                                                      |
  | `py`    | <ApiLink name="int32_t" />                                                               | X coordinate of a point of the line                                                                                                                                                                                                      |
  | `angle` | <ApiLink name="int16_t" />                                                               | right 0 deg, bottom: 90                                                                                                                                                                                                                  |
  | `side`  | <ApiLink name="lv_draw_sw_mask_line_side_t" />                                           | an element of `lv_draw_mask_line_side_t` to describe which side to keep. With `LV_DRAW_MASK_LINE_SIDE_LEFT/RIGHT` and horizontal line all pixels are kept With `LV_DRAW_MASK_LINE_SIDE_TOP/BOTTOM` and vertical line all pixels are kept |
</ApiMember>

<ApiMember kind="function" name="lv_draw_sw_mask_angle_init" file="draw/sw/lv_draw_sw_mask.h" line="137" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L137">
  lv_draw_sw_mask_angle_init [#lv_draw_sw_mask_angle_init]

  Initialize an angle mask.

  ```c title=" " lineNumbers=1
  void lv_draw_sw_mask_angle_init(lv_draw_sw_mask_angle_param_t *param, int32_t vertex_x, int32_t vertex_y, int32_t start_angle, int32_t end_angle)
  ```

  <span className="sr-only">
    Parameters
  </span>

  | Name          | Type                                                                                       | Description                                                       |
  | ------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
  | `param`       | <ApiLink name="lv_draw_sw_mask_angle_param_t" display="lv_draw_sw_mask_angle_param_t *" /> | pointer to a `lv_draw_mask_param_t` to initialize                 |
  | `vertex_x`    | <ApiLink name="int32_t" />                                                                 | X coordinate of the angle vertex (absolute coordinates)           |
  | `vertex_y`    | <ApiLink name="int32_t" />                                                                 | Y coordinate of the angle vertex (absolute coordinates)           |
  | `start_angle` | <ApiLink name="int32_t" />                                                                 | start angle in degrees. 0 deg on the right, 90 deg, on the bottom |
  | `end_angle`   | <ApiLink name="int32_t" />                                                                 | end angle                                                         |
</ApiMember>

<ApiMember kind="function" name="lv_draw_sw_mask_radius_init" file="draw/sw/lv_draw_sw_mask.h" line="147" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L147">
  lv_draw_sw_mask_radius_init [#lv_draw_sw_mask_radius_init]

  Initialize a fade mask.

  ```c title=" " lineNumbers=1
  void lv_draw_sw_mask_radius_init(lv_draw_sw_mask_radius_param_t *param, const lv_area_t *rect, int32_t radius, bool inv)
  ```

  <span className="sr-only">
    Parameters
  </span>

  | Name     | Type                                                                                         | Description                                                                          |
  | -------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
  | `param`  | <ApiLink name="lv_draw_sw_mask_radius_param_t" display="lv_draw_sw_mask_radius_param_t *" /> | pointer to an `lv_draw_mask_radius_param_t` to initialize                            |
  | `rect`   | <ApiLink name="lv_area_t" display="const lv_area_t *" />                                     | coordinates of the rectangle to affect (absolute coordinates)                        |
  | `radius` | <ApiLink name="int32_t" />                                                                   | radius of the rectangle                                                              |
  | `inv`    | <ApiLink name="bool" />                                                                      | true: keep the pixels inside the rectangle; keep the pixels outside of the rectangle |
</ApiMember>

<ApiMember kind="function" name="lv_draw_sw_mask_fade_init" file="draw/sw/lv_draw_sw_mask.h" line="159" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L159">
  lv_draw_sw_mask_fade_init [#lv_draw_sw_mask_fade_init]

  Initialize a fade mask.

  ```c title=" " lineNumbers=1
  void lv_draw_sw_mask_fade_init(lv_draw_sw_mask_fade_param_t *param, const lv_area_t *coords, lv_opa_t opa_top, int32_t y_top, lv_opa_t opa_bottom, int32_t y_bottom)
  ```

  <span className="sr-only">
    Parameters
  </span>

  | Name         | Type                                                                                     | Description                                                    |
  | ------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
  | `param`      | <ApiLink name="lv_draw_sw_mask_fade_param_t" display="lv_draw_sw_mask_fade_param_t *" /> | pointer to a `lv_draw_mask_param_t` to initialize              |
  | `coords`     | <ApiLink name="lv_area_t" display="const lv_area_t *" />                                 | coordinates of the area to affect (absolute coordinates)       |
  | `opa_top`    | <ApiLink name="lv_opa_t" />                                                              | opacity on the top                                             |
  | `y_top`      | <ApiLink name="int32_t" />                                                               | at which coordinate start to change to opacity to `opa_bottom` |
  | `opa_bottom` | <ApiLink name="lv_opa_t" />                                                              | opacity at the bottom                                          |
  | `y_bottom`   | <ApiLink name="int32_t" />                                                               | at which coordinate reach `opa_bottom`.                        |
</ApiMember>

<ApiMember kind="function" name="lv_draw_sw_mask_map_init" file="draw/sw/lv_draw_sw_mask.h" line="169" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L169">
  lv_draw_sw_mask_map_init [#lv_draw_sw_mask_map_init]

  Initialize a map mask.

  ```c title=" " lineNumbers=1
  void lv_draw_sw_mask_map_init(lv_draw_sw_mask_map_param_t *param, const lv_area_t *coords, const lv_opa_t *map)
  ```

  <span className="sr-only">
    Parameters
  </span>

  | Name     | Type                                                                                   | Description                                       |
  | -------- | -------------------------------------------------------------------------------------- | ------------------------------------------------- |
  | `param`  | <ApiLink name="lv_draw_sw_mask_map_param_t" display="lv_draw_sw_mask_map_param_t *" /> | pointer to a `lv_draw_mask_param_t` to initialize |
  | `coords` | <ApiLink name="lv_area_t" display="const lv_area_t *" />                               | coordinates of the map (absolute coordinates)     |
  | `map`    | <ApiLink name="lv_opa_t" display="const lv_opa_t *" />                                 | array of bytes with the mask values               |
</ApiMember>

Enums [#enums]

<ApiMember kind="enum" name="lv_draw_sw_mask_res_t" file="draw/sw/lv_draw_sw_mask.h" line="35" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L35">
  lv_draw_sw_mask_res_t [#lv_draw_sw_mask_res_t]

  | Name                             |
  | -------------------------------- |
  | `LV_DRAW_SW_MASK_RES_TRANSP`     |
  | `LV_DRAW_SW_MASK_RES_FULL_COVER` |
  | `LV_DRAW_SW_MASK_RES_CHANGED`    |
  | `LV_DRAW_SW_MASK_RES_UNKNOWN`    |
</ApiMember>

<ApiMember kind="enum" name="lv_draw_sw_mask_type_t" file="draw/sw/lv_draw_sw_mask.h" line="44" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L44">
  lv_draw_sw_mask_type_t [#lv_draw_sw_mask_type_t]

  | Name                          |
  | ----------------------------- |
  | `LV_DRAW_SW_MASK_TYPE_LINE`   |
  | `LV_DRAW_SW_MASK_TYPE_ANGLE`  |
  | `LV_DRAW_SW_MASK_TYPE_RADIUS` |
  | `LV_DRAW_SW_MASK_TYPE_FADE`   |
  | `LV_DRAW_SW_MASK_TYPE_MAP`    |
</ApiMember>

<ApiMember kind="enum" name="lv_draw_sw_mask_line_side_t" file="draw/sw/lv_draw_sw_mask.h" line="52" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L52">
  lv_draw_sw_mask_line_side_t [#lv_draw_sw_mask_line_side_t]

  | Name                               | Value |
  | ---------------------------------- | ----- |
  | `LV_DRAW_SW_MASK_LINE_SIDE_LEFT`   | `0`   |
  | `LV_DRAW_SW_MASK_LINE_SIDE_RIGHT`  |       |
  | `LV_DRAW_SW_MASK_LINE_SIDE_TOP`    |       |
  | `LV_DRAW_SW_MASK_LINE_SIDE_BOTTOM` |       |
</ApiMember>

<TypeUsedBy name="lv_draw_sw_mask_line_side_t" count="2">
  * `lv_draw_sw_mask_line_points_init` — param `side`
  * `lv_draw_sw_mask_line_angle_init` — param `side`
</TypeUsedBy>

Typedefs [#typedefs]

<ApiMember kind="typedef" name="lv_draw_sw_mask_xcb_t" file="draw/sw/lv_draw_sw_mask.h" line="63" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L63">
  lv_draw_sw_mask_xcb_t [#lv_draw_sw_mask_xcb_t]

  ```c title=" " lineNumbers=1
  typedef lv_draw_sw_mask_res_t(* lv_draw_sw_mask_xcb_t) (lv_opa_t *mask_buf, int32_t abs_x, int32_t abs_y, int32_t len, void *p)
  ```

  A common callback type for every mask type. Used internally by the library.
</ApiMember>

Macros [#macros]

<ApiMember kind="macro" name="LV_MASK_ID_INV" file="draw/sw/lv_draw_sw_mask.h" line="24" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L24">
  LV_MASK_ID_INV [#lv_mask_id_inv]

  ```c title=" " lineNumbers=1
  #define LV_MASK_ID_INV (-1)
  ```
</ApiMember>

<ApiMember kind="macro" name="LV_MASK_MAX_NUM" file="draw/sw/lv_draw_sw_mask.h" line="26" url="https://github.com/lvgl/lvgl/tree/a7b95c5b0839ce901c09c205610bc2c77cc3345d/src/draw/sw/lv_draw_sw_mask.h#L26">
  LV_MASK_MAX_NUM [#lv_mask_max_num]

  ```c title=" " lineNumbers=1
  #define LV_MASK_MAX_NUM 16
  ```
</ApiMember>

Dependencies [#dependencies]

<FileIncludes includes="[&#x22;lv_area.h&#x22;, &#x22;lv_color.h&#x22;, &#x22;lv_math.h&#x22;, &#x22;lv_types.h&#x22;]" includedBy="[&#x22;lv_draw_sw_blend.h&#x22;, &#x22;lv_draw_sw_mask_private.h&#x22;]" transitiveIncludes="[&#x22;lv_assert.h&#x22;, &#x22;lv_color_op.h&#x22;, &#x22;lv_conf_internal.h&#x22;, &#x22;lv_conf_kconfig.h&#x22;, &#x22;lv_log.h&#x22;, &#x22;lv_mem.h&#x22;, &#x22;lv_palette.h&#x22;, &#x22;lv_string.h&#x22;]" />