libwebsockets
Lightweight C library for HTML5 websockets
lws-display.h
Go to the documentation of this file.
1 /*
2  * lws abstract display
3  *
4  * Copyright (C) 2019 - 2022 Andy Green <andy@warmcat.com>
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22  * IN THE SOFTWARE.
23  */
24 
25 #if !defined(__LWS_DISPLAY_H__)
26 #define __LWS_DISPLAY_H__
27 
28 typedef int16_t lws_display_list_coord_t;
29 typedef uint16_t lws_display_scalar;
30 typedef uint16_t lws_display_rotation_t;
31 typedef uint32_t lws_display_colour_t;
32 typedef uint16_t lws_display_palette_idx_t;
33 
34 typedef struct lws_box {
35  lws_fx_t x;
36  lws_fx_t y;
37  lws_fx_t w;
38  lws_fx_t h;
39 } lws_box_t;
40 
41 struct lws_display_state;
42 struct lws_display;
43 
44 typedef enum {
45  LWSSURF_TRUECOLOR32,
46  LWSSURF_565,
47  LWSSURF_PALETTE,
48  LWSSURF_QUANTIZED_4BPP
49 } lws_surface_type_t;
50 
51 typedef struct lws_surface_info {
52  lws_fx_t wh_px[2];
53  lws_fx_t wh_mm[2];
54  const lws_display_colour_t *palette;
55  size_t palette_depth;
56  lws_surface_type_t type;
57  uint8_t greyscale:1; /* line: 0 = RGBA, 1 = YA */
58  uint8_t partial:1; /* can handle partial */
59 } lws_surface_info_t;
60 
61 typedef struct lws_greyscale_error {
62  int16_t rgb[1];
63 } lws_greyscale_error_t;
64 
65 typedef struct lws_colour_error {
66  int16_t rgb[3];
67 } lws_colour_error_t;
68 
69 typedef union {
70  lws_greyscale_error_t grey; /* when ic->greyscale set */
71  lws_colour_error_t colour; /* when ic->greyscale == 0 */
72 } lws_surface_error_t;
73 
74 LWS_VISIBLE LWS_EXTERN void
75 lws_surface_set_px(const lws_surface_info_t *ic, uint8_t *line, int x,
76  const lws_display_colour_t *c);
77 
78 LWS_VISIBLE LWS_EXTERN lws_display_palette_idx_t
79 lws_display_palettize_grey(const lws_surface_info_t *ic,
80  const lws_display_colour_t *palette, size_t pdepth,
81  lws_display_colour_t c, lws_greyscale_error_t *ectx);
82 
83 LWS_VISIBLE LWS_EXTERN lws_display_palette_idx_t
84 lws_display_palettize_col(const lws_surface_info_t *ic,
85  const lws_display_colour_t *palette, size_t pdepth,
86  lws_display_colour_t c, lws_colour_error_t *ectx);
87 
88 /*
89  * This is embedded in the actual display implementation object at the top,
90  * so a pointer to this can be cast to a pointer to the implementation object
91  * by any code that is specific to how it was implemented.
92  *
93  * Notice for the backlight / display intensity we contain pwm_ops... these can
94  * be some other pwm_ops like existing gpio pwm ops, or handled in a customized
95  * way like set oled contrast. Either way, the pwm level is arrived at via a
96  * full set of lws_led_sequences capable of generic lws transitions
97  */
98 
99 typedef struct lws_display {
100  int (*init)(struct lws_display_state *lds);
101  const lws_pwm_ops_t *bl_pwm_ops;
102  int (*contrast)(struct lws_display_state *lds, uint8_t contrast);
103  int (*blit)(struct lws_display_state *lds, const uint8_t *src,
104  lws_box_t *box, lws_dll2_owner_t *ids);
105  int (*power)(struct lws_display_state *lds, int state);
106 
107  const lws_led_sequence_def_t *bl_active;
108  const lws_led_sequence_def_t *bl_dim;
109  const lws_led_sequence_def_t *bl_transition;
110 
111  const char *name;
112  void *variant;
113 
114  int bl_index;
115 
116  lws_surface_info_t ic;
117 
118  uint16_t latency_wake_ms;
119  /**< ms required after wake from sleep before display usable again...
120  * delay bringing up the backlight for this amount of time on wake.
121  * This is managed via a sul on the event loop, not blocking. */
122  uint16_t latency_update_ms;
123  /**< nominal update latency in ms */
124 } lws_display_t;
125 
126 /*
127  * This contains dynamic data related to display state
128  */
129 
130 enum lws_display_controller_state {
131  LWSDISPS_OFF,
132  LWSDISPS_AUTODIMMED, /* is in pre- blanking static dim mode */
133  LWSDISPS_BECOMING_ACTIVE, /* waiting for wake latency before active */
134  LWSDISPS_ACTIVE, /* is active */
135  LWSDISPS_GOING_OFF /* dimming then off */
136 };
137 
138 typedef struct lws_display_state {
139 
140  lws_sorted_usec_list_t sul_autodim;
141 
142  char current_url[96];
143 
144  const lws_display_t *disp;
145  struct lws_context *ctx;
146 
147  void *priv; /* subclass driver alloc'd priv */
148 
149  int autodim_ms;
150  int off_ms;
151 
152  struct lws_led_state *bl_lcs;
153 
154  lws_led_state_chs_t chs;
155  /* set of sequencer transition channels */
156 
157  enum lws_display_controller_state state;
158 
159  char display_busy;
160 
161 } lws_display_state_t;
162 
163 /* Used for async display driver events, eg, EPD refresh completion */
164 typedef int (*lws_display_completion_t)(lws_display_state_t *lds, int a);
165 
166 /**
167  * lws_display_state_init() - initialize display states
168  *
169  * \param lds: the display state object
170  * \param ctx: the lws context
171  * \param autodim_ms: ms since last active report to dim display (<0 = never)
172  * \param off_ms: ms since dim to turn display off (<0 = never)
173  * \param bl_lcs: the led controller instance that has the backlight
174  * \param disp: generic display object we belong to
175  *
176  * This initializes a display's state, and sets up the optional screen auto-dim
177  * and blanking on inactive, and gradual brightness change timer.
178  *
179  * - auto-dim then off: set autodim to some ms and off_ms to some ms
180  * - auto-dim only: set autodim to some ms and off_ms to -1
181  * - off-only: set autodim to some ms and off_ms to 0
182  * - neither: set both autodim and off_ms to -1
183  */
184 LWS_VISIBLE LWS_EXTERN void
185 lws_display_state_init(lws_display_state_t *lds, struct lws_context *ctx,
186  int autodim_ms, int off_ms, struct lws_led_state *bl_lcs,
187  const lws_display_t *disp);
188 
189 /**
190  * lws_display_state_set_brightness() - gradually change the brightness
191  *
192  * \param lds: the display state we are changing
193  * \param target: the target brightness to transition to
194  *
195  * Adjusts the brightness gradually twoards the target at 20Hz
196  */
197 LWS_VISIBLE LWS_EXTERN void
198 lws_display_state_set_brightness(lws_display_state_t *lds,
199  const lws_led_sequence_def_t *pwmseq);
200 
201 /*
202  * lws_display_state_active() - inform the system the display is active
203  *
204  * \param lds: the display state we are marking as active
205  *
206  * Resets the auto-dim and auto-off timers and makes sure the display is on and
207  * at the active brightness level
208  */
209 LWS_VISIBLE LWS_EXTERN void
210 lws_display_state_active(lws_display_state_t *lds);
211 
212 /*
213  * lws_display_state_off() - turns off the related display
214  *
215  * \param lds: the display state we are turning off
216  *
217  * Turns the display to least power mode or completely off if possible.
218  * Disables the timers related to dimming and blanking.
219  */
220 LWS_VISIBLE LWS_EXTERN void
221 lws_display_state_off(lws_display_state_t *lds);
222 
223 #endif