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
33
34typedef struct lws_box {
39} lws_box_t;
40
42struct lws_display;
43
44typedef enum {
49} lws_surface_type_t;
50
51typedef struct lws_surface_info {
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
61typedef struct lws_greyscale_error {
63} lws_greyscale_error_t;
64
65typedef struct lws_colour_error {
67} lws_colour_error_t;
68
69typedef 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
74LWS_VISIBLE LWS_EXTERN void
75lws_surface_set_px(const lws_surface_info_t *ic, uint8_t *line, int x,
76 const lws_display_colour_t *c);
77
78LWS_VISIBLE LWS_EXTERN lws_display_palette_idx_t
79lws_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
83LWS_VISIBLE LWS_EXTERN lws_display_palette_idx_t
84lws_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
99typedef struct lws_display {
100 int (*init)(struct lws_display_state *lds);
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
110
111 const char *name;
112 void *variant;
113
115
116 lws_surface_info_t ic;
117
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. */
123 /**< nominal update latency in ms */
124} lws_display_t;
125
126/*
127 * This contains dynamic data related to display state
128 */
129
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 */
137
138typedef struct lws_display_state {
139
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
151
152 struct lws_led_state *bl_lcs;
153
155 /* set of sequencer transition channels */
156
158
160
161} lws_display_state_t;
162
163/* Used for async display driver events, eg, EPD refresh completion */
164typedef 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 */
184LWS_VISIBLE LWS_EXTERN void
185lws_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 */
197LWS_VISIBLE LWS_EXTERN void
198lws_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 */
209LWS_VISIBLE LWS_EXTERN void
210lws_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 */
220LWS_VISIBLE LWS_EXTERN void
221lws_display_state_off(lws_display_state_t *lds);
222
223#endif
lws_fx_t w
Definition: lws-display.h:37
LWS_VISIBLE LWS_EXTERN lws_display_palette_idx_t lws_display_palettize_col(const lws_surface_info_t *ic, const lws_display_colour_t *palette, size_t pdepth, lws_display_colour_t c, lws_colour_error_t *ectx)
LWS_VISIBLE LWS_EXTERN void lws_surface_set_px(const lws_surface_info_t *ic, uint8_t *line, int x, const lws_display_colour_t *c)
const lws_display_colour_t * palette
Definition: lws-display.h:54
enum lws_display_controller_state state
Definition: lws-display.h:157
LWS_VISIBLE LWS_EXTERN void lws_display_state_off(lws_display_state_t *lds)
int(* lws_display_completion_t)(lws_display_state_t *lds, int a)
Definition: lws-display.h:164
const lws_display_t * disp
Definition: lws-display.h:144
lws_led_state_chs_t chs
Definition: lws-display.h:154
lws_fx_t h
Definition: lws-display.h:38
LWS_VISIBLE LWS_EXTERN void lws_display_state_active(lws_display_state_t *lds)
lws_surface_type_t type
Definition: lws-display.h:56
LWS_VISIBLE LWS_EXTERN lws_display_palette_idx_t lws_display_palettize_grey(const lws_surface_info_t *ic, const lws_display_colour_t *palette, size_t pdepth, lws_display_colour_t c, lws_greyscale_error_t *ectx)
uint16_t lws_display_palette_idx_t
Definition: lws-display.h:32
struct lws_context * ctx
Definition: lws-display.h:145
uint16_t lws_display_rotation_t
Definition: lws-display.h:30
lws_colour_error_t colour
Definition: lws-display.h:71
uint32_t lws_display_colour_t
Definition: lws-display.h:31
lws_fx_t x
Definition: lws-display.h:35
int16_t lws_display_list_coord_t
Definition: lws-display.h:28
lws_display_controller_state
Definition: lws-display.h:130
@ LWSDISPS_AUTODIMMED
Definition: lws-display.h:132
@ LWSDISPS_ACTIVE
Definition: lws-display.h:134
@ LWSDISPS_OFF
Definition: lws-display.h:131
@ LWSDISPS_BECOMING_ACTIVE
Definition: lws-display.h:133
@ LWSDISPS_GOING_OFF
Definition: lws-display.h:135
LWS_VISIBLE LWS_EXTERN void lws_display_state_set_brightness(lws_display_state_t *lds, const lws_led_sequence_def_t *pwmseq)
lws_sorted_usec_list_t sul_autodim
Definition: lws-display.h:140
lws_fx_t y
Definition: lws-display.h:36
uint16_t lws_display_scalar
Definition: lws-display.h:29
lws_greyscale_error_t grey
Definition: lws-display.h:70
char current_url[96]
Definition: lws-display.h:142
size_t palette_depth
Definition: lws-display.h:55
LWS_VISIBLE LWS_EXTERN void lws_display_state_init(lws_display_state_t *lds, struct lws_context *ctx, int autodim_ms, int off_ms, struct lws_led_state *bl_lcs, const lws_display_t *disp)
uint8_t greyscale
Definition: lws-display.h:57
struct lws_led_state * bl_lcs
Definition: lws-display.h:152
@ LWSSURF_QUANTIZED_4BPP
Definition: lws-display.h:48
@ LWSSURF_565
Definition: lws-display.h:46
@ LWSSURF_TRUECOLOR32
Definition: lws-display.h:45
@ LWSSURF_PALETTE
Definition: lws-display.h:47
int(* contrast)(struct lws_display_state *lds, uint8_t contrast)
Definition: lws-display.h:102
uint16_t latency_wake_ms
Definition: lws-display.h:118
const lws_led_sequence_def_t * bl_active
Definition: lws-display.h:107
lws_surface_info_t ic
Definition: lws-display.h:116
const char * name
Definition: lws-display.h:111
int(* blit)(struct lws_display_state *lds, const uint8_t *src, lws_box_t *box, lws_dll2_owner_t *ids)
Definition: lws-display.h:103
const lws_pwm_ops_t * bl_pwm_ops
Definition: lws-display.h:101
void * variant
Definition: lws-display.h:112
const lws_led_sequence_def_t * bl_dim
Definition: lws-display.h:108
const lws_led_sequence_def_t * bl_transition
Definition: lws-display.h:109
uint16_t latency_update_ms
Definition: lws-display.h:122
int(* init)(struct lws_display_state *lds)
Definition: lws-display.h:100
int(* power)(struct lws_display_state *lds, int state)
Definition: lws-display.h:105