acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
Log | Files | Refs | Archive | README | LICENSE

img.md (7058B)

      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/widgets/core/img.md
      4 ```
      5 # Image (lv_img)
      6 
      7 
      8 ## Overview
      9 
     10 Images are the basic object to display images from flash (as arrays) or from files. Images can display symbols (`LV_SYMBOL_...`) too.
     11 
     12 Using the [Image decoder interface](/overview/image.html#image-decoder) custom image formats can be supported as well.
     13 
     14 ## Parts and Styles
     15 - `LV_PART_MAIN` A background rectangle that uses the typical background style properties and the image itself using the image style properties.
     16 
     17 ## Usage
     18 
     19 ### Image source
     20 To provide maximum flexibility, the source of the image can be:
     21 
     22 - a variable in code (a C array with the pixels).
     23 - a file stored externally (e.g. on an SD card).
     24 - a text with [Symbols](/overview/font).
     25 
     26 To set the source of an image, use `lv_img_set_src(img, src)`.
     27 
     28 To generate a pixel array from a PNG, JPG or BMP image, use the [Online image converter tool](https://lvgl.io/tools/imageconverter) and set the converted image with its pointer: `lv_img_set_src(img1, &converted_img_var);`
     29 To make the variable visible in the C file, you need to declare it with `LV_IMG_DECLARE(converted_img_var)`.
     30 
     31 To use external files, you also need to convert the image files using the online converter tool but now you should select the binary output format.
     32 You also need to use LVGL's file system module and register a driver with some functions for the basic file operation. Go to the [File system](/overview/file-system) to learn more.
     33 To set an image sourced from a file, use `lv_img_set_src(img, "S:folder1/my_img.bin")`.
     34 
     35 You can also set a symbol similarly to [Labels](/widgets/core/label). In this case, the image will be rendered as text according to the *font* specified in the style.  It enables to use of light-weight monochrome "letters" instead of real images. You can set symbol like `lv_img_set_src(img1, LV_SYMBOL_OK)`.
     36 
     37 ### Label as an image
     38 Images and labels are sometimes used to convey the same thing. For example, to describe what a button does.
     39 Therefore, images and labels are somewhat interchangeable, that is the images can display texts by using `LV_SYMBOL_DUMMY` as the prefix of the text. For example, `lv_img_set_src(img, LV_SYMBOL_DUMMY "Some text")`.
     40 
     41 
     42 ### Transparency
     43 The internal (variable) and external images support 2 transparency handling methods:
     44 
     45 - **Chroma-keying** - Pixels with `LV_COLOR_CHROMA_KEY` (*lv_conf.h*) color will be transparent.
     46 - **Alpha byte** - An alpha byte is added to every pixel that contains the pixel's opacity
     47 
     48 ### Palette and Alpha index
     49 Besides the *True color* (RGB) color format, the following formats are supported:
     50 - **Indexed** - Image has a palette.
     51 - **Alpha indexed** - Only alpha values are stored.
     52 
     53 These options can be selected in the image converter. To learn more about the color formats, read the [Images](/overview/image) section.
     54 
     55 ### Recolor
     56 A color can be mixed with every pixel of an image with a given intensity.
     57 This can be useful to show different states (checked, inactive, pressed, etc.) of an image without storing more versions of the same image.
     58 This feature can be enabled in the style by setting `img_recolor_opa` between `LV_OPA_TRANSP` (no recolor, value: 0) and `LV_OPA_COVER` (full recolor, value: 255).
     59 The default value is `LV_OPA_TRANSP` so this feature is disabled.
     60 
     61 The color to mix is set by `img_recolor`.
     62 
     63 ### Auto-size
     64 If the width or height of the image object is set to `LV_SIZE_CONTENT` the object's size will be set according to the size of the image source in the respective direction.
     65 
     66 ### Mosaic
     67 If the object's size is greater than the image size in any directions, then the image will be repeated like a mosaic.
     68 This allows creation a large image from only a very narrow source.
     69 For example, you can have a *300 x 5* image with a special gradient and set it as a wallpaper using the mosaic feature.
     70 
     71 ### Offset
     72 With `lv_img_set_offset_x(img, x_ofs)` and `lv_img_set_offset_y(img, y_ofs)`, you can add some offset to the displayed image.
     73 Useful if the object size is smaller than the image source size.
     74 Using the offset parameter a [Texture atlas](https://en.wikipedia.org/wiki/Texture_atlas) or a "running image" effect can be created by [Animating](/overview/animation) the x or y offset.
     75 
     76 ## Transformations
     77 
     78 Using the `lv_img_set_zoom(img, factor)` the images will be zoomed. Set `factor` to `256` or `LV_IMG_ZOOM_NONE` to disable zooming.
     79 A larger value enlarges the images (e.g. `512` double size), a smaller value shrinks it (e.g. `128` half size).
     80 Fractional scale works as well. E.g. `281` for 10% enlargement.
     81 
     82 To rotate the image use `lv_img_set_angle(img, angle)`. Angle has 0.1 degree precision, so for 45.8° set 458.
     83 
     84 The `transform_zoom` and `transform_angle` style properties are also used to determine the final zoom and angle.
     85 
     86 By default, the pivot point of the rotation is the center of the image. It can be changed with `lv_img_set_pivot(img, pivot_x, pivot_y)`. `0;0` is the top left corner.
     87 
     88 The quality of the transformation can be adjusted with `lv_img_set_antialias(img, true/false)`. With enabled anti-aliasing the transformations are higher quality but slower.
     89 
     90 The transformations require the whole image to be available. Therefore indexed images (`LV_IMG_CF_INDEXED_...`), alpha only images (`LV_IMG_CF_ALPHA_...`) or images from files can not be transformed.
     91 In other words transformations work only on true color images stored as C array, or if a custom [Image decoder](/overview/images#image-edecoder) returns the whole image.
     92 
     93 Note that the real coordinates of image objects won't change during transformation. That is `lv_obj_get_width/height/x/y()` will return the original, non-zoomed coordinates.
     94 
     95 ### Size mode
     96 
     97 By default, when the image is zoomed or rotated the real coordinates of the image object are not changed.
     98 The larger content simply overflows the object's boundaries.
     99 It also means the layouts are not affected the by the transformations.
    100 
    101 If you need the object size to be updated to the transformed size set `lv_img_set_size_mode(img, LV_IMG_SIZE_MODE_REAL)`. (The previous mode is the default and called `LV_IMG_SIZE_MODE_VIRTUAL`).
    102 In this case if the width/height of the object is set to `LV_SIZE_CONTENT` the object's size will be set to the zoomed and rotated size.
    103 If an explicit size is set then the overflowing content will be cropped.
    104 
    105 ### Rounded image
    106 
    107 You can use `lv_obj_set_style_radius` to set radius to an image, and enable `lv_obj_set_style_clip_corner` to clip the
    108 content to rounded rectangle or circular shape. Please note this will have some negative performance impact to CPU
    109 based renderers.
    110 
    111 ## Events
    112 No special events are sent by image objects.
    113 
    114 See the events of the [Base object](/widgets/obj) too.
    115 
    116 Learn more about [Events](/overview/event).
    117 
    118 ## Keys
    119 No *Keys* are processed by the object type.
    120 
    121 Learn more about [Keys](/overview/indev).
    122 
    123 ## Example
    124 
    125 ```eval_rst
    126 
    127 .. include:: ../../../examples/widgets/img/index.rst
    128 
    129 ```
    130 
    131 ## API
    132 
    133 ```eval_rst
    134 
    135 .. doxygenfile:: lv_img.h
    136   :project: lvgl
    137 
    138 ```