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
28typedef int16_t lws_display_list_coord_t;
29typedef uint16_t lws_display_scalar;
30typedef uint16_t lws_display_rotation_t;
31typedef uint32_t lws_display_colour_t;
32typedef uint16_t lws_display_palette_idx_t;
33
34typedef 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
41struct lws_display_state;
42struct lws_display;
43
44typedef enum {
45 LWSSURF_TRUECOLOR32,
46 LWSSURF_565,
47 LWSSURF_PALETTE,
48 LWSSURF_QUANTIZED_4BPP
49} lws_surface_type_t;
50
51typedef 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 uint8_t render_to_rgba:1; /* render to 32-bit RGBA, not 24-bit RGB */
60} lws_surface_info_t;
61
62typedef struct lws_greyscale_error {
63 int16_t rgb[1];
64} lws_greyscale_error_t;
65
66typedef struct lws_colour_error {
67 int16_t rgb[3];
68} lws_colour_error_t;
69
70typedef union {
71 lws_greyscale_error_t grey; /* when ic->greyscale set */
72 lws_colour_error_t colour; /* when ic->greyscale == 0 */
73} lws_surface_error_t;
74
75LWS_VISIBLE LWS_EXTERN void
76lws_surface_set_px(const lws_surface_info_t *ic, uint8_t *line, int x,
77 const lws_display_colour_t *c);
78
79LWS_VISIBLE LWS_EXTERN lws_display_palette_idx_t
80lws_display_palettize_grey(const lws_surface_info_t *ic,
81 const lws_display_colour_t *palette, size_t pdepth,
82 lws_display_colour_t c, lws_greyscale_error_t *ectx);
83
84LWS_VISIBLE LWS_EXTERN lws_display_palette_idx_t
85lws_display_palettize_col(const lws_surface_info_t *ic,
86 const lws_display_colour_t *palette, size_t pdepth,
87 lws_display_colour_t c, lws_colour_error_t *ectx);
88
89/*
90 * This is embedded in the actual display implementation object at the top,
91 * so a pointer to this can be cast to a pointer to the implementation object
92 * by any code that is specific to how it was implemented.
93 *
94 * Notice for the backlight / display intensity we contain pwm_ops... these can
95 * be some other pwm_ops like existing gpio pwm ops, or handled in a customized
96 * way like set oled contrast. Either way, the pwm level is arrived at via a
97 * full set of lws_led_sequences capable of generic lws transitions
98 */
99
100typedef struct lws_display {
101 int (*init)(struct lws_display_state *lds);
102 const lws_pwm_ops_t *bl_pwm_ops;
103 int (*contrast)(struct lws_display_state *lds, uint8_t contrast);
104 int (*blit)(struct lws_display_state *lds, const uint8_t *src,
105 lws_box_t *box, lws_dll2_owner_t *ids);
106 int (*power)(struct lws_display_state *lds, int state);
107
108 const lws_led_sequence_def_t *bl_active;
109 const lws_led_sequence_def_t *bl_dim;
110 const lws_led_sequence_def_t *bl_transition;
111
112 const char *name;
113 void *variant;
114
115 int bl_index;
116
117 lws_surface_info_t ic;
118
119 uint16_t latency_wake_ms;
120 /**< ms required after wake from sleep before display usable again...
121 * delay bringing up the backlight for this amount of time on wake.
122 * This is managed via a sul on the event loop, not blocking. */
123 uint16_t latency_update_ms;
124 /**< nominal update latency in ms */
125} lws_display_t;
126
127/*
128 * This contains dynamic data related to display state
129 */
130
131enum lws_display_controller_state {
132 LWSDISPS_OFF,
133 LWSDISPS_AUTODIMMED, /* is in pre- blanking static dim mode */
134 LWSDISPS_BECOMING_ACTIVE, /* waiting for wake latency before active */
135 LWSDISPS_ACTIVE, /* is active */
136 LWSDISPS_GOING_OFF /* dimming then off */
137};
138
139typedef struct lws_display_state {
140
141 lws_sorted_usec_list_t sul_autodim;
142
143 char current_url[96];
144
145 const lws_display_t *disp;
146 struct lws_context *ctx;
147
148 void *priv; /* subclass driver alloc'd priv */
149
150 int autodim_ms;
151 int off_ms;
152
153 struct lws_led_state *bl_lcs;
154
155 lws_led_state_chs_t chs;
156 /* set of sequencer transition channels */
157
158 enum lws_display_controller_state state;
159
160 char display_busy;
161
162} lws_display_state_t;
163
164/* Used for async display driver events, eg, EPD refresh completion */
165typedef int (*lws_display_completion_t)(lws_display_state_t *lds, int a);
166
167/**
168 * lws_display_state_init() - initialize display states
169 *
170 * \param lds: the display state object
171 * \param ctx: the lws context
172 * \param autodim_ms: ms since last active report to dim display (<0 = never)
173 * \param off_ms: ms since dim to turn display off (<0 = never)
174 * \param bl_lcs: the led controller instance that has the backlight
175 * \param disp: generic display object we belong to
176 *
177 * This initializes a display's state, and sets up the optional screen auto-dim
178 * and blanking on inactive, and gradual brightness change timer.
179 *
180 * - auto-dim then off: set autodim to some ms and off_ms to some ms
181 * - auto-dim only: set autodim to some ms and off_ms to -1
182 * - off-only: set autodim to some ms and off_ms to 0
183 * - neither: set both autodim and off_ms to -1
184 */
185LWS_VISIBLE LWS_EXTERN void
186lws_display_state_init(lws_display_state_t *lds, struct lws_context *ctx,
187 int autodim_ms, int off_ms, struct lws_led_state *bl_lcs,
188 const lws_display_t *disp);
189
190/**
191 * lws_display_state_set_brightness() - gradually change the brightness
192 *
193 * \param lds: the display state we are changing
194 * \param target: the target brightness to transition to
195 *
196 * Adjusts the brightness gradually twoards the target at 20Hz
197 */
198LWS_VISIBLE LWS_EXTERN void
199lws_display_state_set_brightness(lws_display_state_t *lds,
200 const lws_led_sequence_def_t *pwmseq);
201
202/*
203 * lws_display_state_active() - inform the system the display is active
204 *
205 * \param lds: the display state we are marking as active
206 *
207 * Resets the auto-dim and auto-off timers and makes sure the display is on and
208 * at the active brightness level
209 */
210LWS_VISIBLE LWS_EXTERN void
211lws_display_state_active(lws_display_state_t *lds);
212
213/*
214 * lws_display_state_off() - turns off the related display
215 *
216 * \param lds: the display state we are turning off
217 *
218 * Turns the display to least power mode or completely off if possible.
219 * Disables the timers related to dimming and blanking.
220 */
221LWS_VISIBLE LWS_EXTERN void
222lws_display_state_off(lws_display_state_t *lds);
223
224#endif
225