3 * Contains the graphics metalanguage interface details
12 * https://www.d-rift.nl/combuster/mos3/?p=viewsource&file=/include/common/udi_gfx.h
15 // note that the specification, and thus, the contents of this file is not fixed.
22 #ifndef UDI_GFX_VERSION
23 #error "UDI_GFX_VERSION not defined."
24 #elif UDI_GFX_VERSION != 0x101
25 #error "UDI_GFX_VERSION not supported."
29 * Enumeration: UDI_GFX_PROP
30 * Lists the various UDI properties
33 // General state properties
34 /* Constant: UDI_GFX_PROP_ENABLE
43 * The connector or engine is enabled (nonzero) or disabled (zero). A disabled
44 * engine forwards all data from the previous stage unmodified. A disabled
45 * connector does not send any data over the connector. Drivers may power down
46 * the physical counterparts of disabled components to preserve power, and users
47 * should expect delays when enabling connectors or components representing
48 * framebuffers. Disabling is however not recommended for sprite layers, which
49 * may repeatedly be enabled and disabled. A disabled component can still have
50 * its state changed, and the driver must complete all commands and other state
51 * changes as expected, regardless of disabled or power state. The valid ranges
52 * reported for this property may be 1 (always enabled) or 0-1 (either enabled
55 #define UDI_GFX_PROP_ENABLE 0
56 /* Constant: UDI_GFX_PROP_INPUT
59 * Any valid engine ID, provided no dependency cycles are created, or -1
62 * Any non-empty set of valid values. Often hardwired.
64 * Points to the engine that is processed before this unit. In the case of a
65 * connector, it points to the last engine in a pipeline, and each engine points
66 * to the next engine in the sequence. A value of -1 indicates a source that
67 * only yields black pixels. Implementations must not allow cyclic structures.
68 * Changing this value may reallocate resources, and engines that are no longer
69 * referenced may lose their data (but not their state) when it is not part of
70 * any pipeline. If preservation is required, the ENABLE state should be used
71 * instead. Valid ranges includes one or more from the list of engines and -1
72 * combined. In most cases, this property can not be modified.
74 #define UDI_GFX_PROP_INPUT 1
75 /* Constant: UDI_GFX_PROP_WIDTH
78 * Any non-zero positive number.
81 * Contains at least one valid value. Often only multiples of UNIT_WIDTH
82 * or a power of two are allowed. May be hardwired.
84 * Contains the amount of pixels in the horizontal direction. For connectors,
85 * this is the amount of data pixels rendered horizontally. For engines, this
86 * is the width in pixels of the image. Pixels requested from an engine outside
87 * the range (0..width-1) are defined according to the <UDI_GFX_PROP_CLIP>
88 * property. In some cases, hardware may support only fixed combinations of
89 * width and height. In such cases, changing the width will also change the
90 * height to a corresponding valid number. Valid ranges include any values
91 * strictly above zero. For connectors, expect large continuous ranges, large
92 * ranges with a certain modulus, a limited number of fixed values, or a
95 #define UDI_GFX_PROP_WIDTH 2
96 /* Constant: UDI_GFX_PROP_HEIGHT
99 * Any non-zero positive number.
102 * Contains at least one valid value. Often only multiples of UNIT_HEIGHT
103 * or a power of two are allowed. May be hardwired.
105 * Contains the amount of pixels in the vertical direction. Functions similar
106 * to the width property, but changing it will not alter the width property,
107 * and it's range at any time contains the valid range for the currently
110 #define UDI_GFX_PROP_HEIGHT 3
112 /* Constant: UDI_GFX_PROP_CUSTOM
113 * The first property index of the driver's custom range. These are not assigned
114 * directly assigned by the UDI specification, but may be specified in the
117 #define UDI_GFX_PROP_CUSTOM 1024
121 /* Constant: UDI_GFX_PROP_CLIP
124 * 0 - points outside width x height are passed from next stage
125 * 1 - the engine's contents is tiled with size width x height
126 * 2 - points outside the width overflow into the y coordinate
127 * 3 - points outside the height overflow into the x coordinate
130 * Hardwired zero for connectors. Any non-empty subset for engines, usually
133 * For engines, contains the behaviour for pixels requested outside the width
134 * and height of the engine. Can be either 0 (pass from next stage), 1 (the
135 * coordinates are wrapped modulus the height and width), 2 (the coordinates
136 * overflow onto the next scanline horizontally, and wrap vertically), 3 (the
137 * coordinates overflow onto the next column vertically, and wrap horizontally).
138 * Valid ranges contain one or more of these options. For overlays and sprites,
139 * a value 0 is common. For framebuffers, 2 is the most common value. For
140 * connectors, this property is always 0 since they do not store pixel data
142 #define UDI_GFX_PROP_CLIP 4
144 /* Constant: UDI_GFX_PROP_UNIT_WIDTH
147 * Any non-zero positive value
150 * Any non-empty set of valid values. May be hardwired to 1 for
151 * framebuffers, or a range of small values for hardware scaling, or any
152 * larger hardwired number or set for tiling engines.
154 * Tiles are used to indicate that the hardware groups sets of pixels and have
155 * each group share certain properties, i.e. color or tile index, or share the
156 * same chroma subsample with only a different intensity. If the engine has no
157 * such grouping, or shares all properties over the entire contents, the value
158 * of this property should be 1. Some tile examples include rescaling, where a
159 * tile width of 2 indicates a pixel doubling in X direction, or in text mode
160 * where a tile width of 8 or 9 corresponds with the width of common bitmap
163 #define UDI_GFX_PROP_UNIT_WIDTH 5
165 /* Constant: UDI_GFX_PROP_UNIT_HEIGHT
168 * Any non-zero positive value
171 * Any non-empty set of valid values. May be hardwired to 1 for
172 * framebuffers, or a range of small values for hardware scaling, or any
173 * larger hardwired number or set for tiling engines.
175 * See <UDI_GFX_PROP_UNIT_WIDTH>, but for the Y direction. Common values are
176 * 1-2 for framebuffers (doublescanning on or off), identical to the tile
177 * width, or mostly independent.
179 #define UDI_GFX_PROP_UNIT_HEIGHT 6
181 #define UDI_GFX_PROP_TRANSLATEX 7
182 #define UDI_GFX_PROP_TRANSLATEY 8
183 #define UDI_GFX_PROP_SOURCE_WIDTH 12
184 #define UDI_GFX_PROP_SOURCE_HEIGHT 13
185 #define UDI_GFX_PROP_GL_VERSION 14
186 #define UDI_GFX_PROP_GLES_VERSION 15
187 #define UDI_GFX_PROP_STATE_BLOCK 16
189 * Each engine consists of 1 or more operators
191 #define UDI_GFX_PROP_OPERATOR_INDEX 17 //!< Index of operator to inspect/manipulate
192 #define UDI_GFX_PROP_OPERATOR_OPCODE 18 //!< Operation performed by operator
193 #define UDI_GFX_PROP_OPERATOR_ARG_1 19 //!< argument 1
194 #define UDI_GFX_PROP_OPERATOR_ARG_2 20 //!< argument 2
195 #define UDI_GFX_PROP_OPERATOR_ARG_3 21 //!< argument 3
196 #define UDI_GFX_PROP_COLOR_BITS 22
197 #define UDI_GFX_PROP_GL_TARGET 23
198 #define UDI_GFX_PROP_INPUTX 25
199 #define UDI_GFX_PROP_INPUTY 26
201 // properties for removal:
202 #define UDI_GFX_PROP_STORE_COUNT 24 // not generic
203 #define UDI_GFX_PROP_STORE_WIDTH 9 // not generic
204 #define UDI_GFX_PROP_STORE_HEIGHT 10 // not generic
205 #define UDI_GFX_PROP_STORE_BITS 11 // not generic
206 #define UDI_GFX_PROP_PALETTE 1024 // optional, can be derived from the operator tree
207 #define UDI_GFX_PROP_BUFFER 1025 // optional, can be derived from the operator tree
208 #define UDI_GFX_PROP_TILESHEET 1026 // optional, can be derived from the operator tree
210 // connector properties
211 #define UDI_GFX_PROP_SIGNAL 23
212 #define UDI_GFX_PROP_CONNECTOR_TYPE 24
213 #define UDI_GFX_PROP_VGA_H_FRONT_PORCH 25
214 #define UDI_GFX_PROP_VGA_H_BACK_PORCH 26
215 #define UDI_GFX_PROP_VGA_H_SYNC 27
216 #define UDI_GFX_PROP_VGA_V_FRONT_PORCH 28
217 #define UDI_GFX_PROP_VGA_V_BACK_PORCH 29
218 #define UDI_GFX_PROP_VGA_V_SYNC 30
219 #define UDI_GFX_PROP_DOT_CLOCK 31
220 #define UDI_GFX_PROP_VGA_H_SYNC_POL 32
221 #define UDI_GFX_PROP_VGA_V_SYNC_POL 33
224 * Enumeration: UDI_GFX_SIGNAL
225 * Lists the various signal types
227 #define UDI_GFX_SIGNAL_HIDDEN 0
228 #define UDI_GFX_SIGNAL_INTEGRATED 0
229 #define UDI_GFX_SIGNAL_RGBHV 1
230 #define UDI_GFX_SIGNAL_RGBS 2
231 #define UDI_GFX_SIGNAL_RGSB 3
232 #define UDI_GFX_SIGNAL_YPBPR 4
233 #define UDI_GFX_SIGNAL_DVID 5
234 #define UDI_GFX_SIGNAL_YUV 6
235 #define UDI_GFX_SIGNAL_YIQ 7
236 #define UDI_GFX_SIGNAL_Y_UV 8
237 #define UDI_GFX_SIGNAL_Y_IQ 9
238 #define UDI_GFX_SIGNAL_HDMI 10
239 #define UDI_GFX_SIGNAL_TEXT 11
240 #define UDI_GFX_SIGNAL_CUSTOM 12
243 * Enumeration: UDI_GFX_CONNECTOR
244 * Lists the various external connectors
246 #define UDI_GFX_CONNECTOR_HIDDEN 0
247 #define UDI_GFX_CONNECTOR_VGA 1
248 #define UDI_GFX_CONNECTOR_DVI 2
249 #define UDI_GFX_CONNECTOR_SVIDEO 3
250 #define UDI_GFX_CONNECTOR_COMPONENT 4
251 #define UDI_GFX_CONNECTOR_HDMI 5
252 #define UDI_GFX_CONNECTOR_RF 6
253 #define UDI_GFX_CONNECTOR_SCART 7
254 #define UDI_GFX_CONNECTOR_COMPOSITE 8
257 * Enumeration: UDI_GFX_OPERATOR
258 * Lists the display output operator
260 * a1/a2/a3 represents taking the output of a previous operation
261 * v1/v2/v3 represents the literal value of that argument
263 #define UDI_GFX_OPERATOR_RGB 0 // output = (color) red(a1) + green(a2) + blue(a3) (each component is UDI_GFX_PROP_COLOR_BITS
264 #define UDI_GFX_OPERATOR_YUV 1 // output = (color) Y(a1) + U(a2) + V(a3)
265 #define UDI_GFX_OPERATOR_YIQ 2 // output = (color) Y(a1) + I(a2) + Q(a3)
266 #define UDI_GFX_OPERATOR_I 3 // output = (color) intensity(a1)
267 #define UDI_GFX_OPERATOR_ALPHA 4 // output = (color) a1 + alpha(a2)
268 #define UDI_GFX_OPERATOR_ADD 5 // output = a1 + a2 + v3
269 #define UDI_GFX_OPERATOR_SUB 6 // output = a1 - a2 - v3
270 #define UDI_GFX_OPERATOR_MUL 7 // output = a1 * a2
271 #define UDI_GFX_OPERATOR_DIV 8 // output = a1 / a2
272 #define UDI_GFX_OPERATOR_MAD 9 // output = a1 * a2 + a3
273 #define UDI_GFX_OPERATOR_FRC 10 // output = (a1 * a2) / a3
274 #define UDI_GFX_OPERATOR_SHR 11 // output = a1 >> (a2 + v3)
275 #define UDI_GFX_OPERATOR_SHL 12 // output = a1 << (a2 + v3)
276 #define UDI_GFX_OPERATOR_ROR 13 // output = a1 >> a2 (over a3 bits)
277 #define UDI_GFX_OPERATOR_ROL 14 // output = a1 << a2 (over a3 bits)
278 #define UDI_GFX_OPERATOR_SAR 15 // output = a1 >> a2 (width is a3 bits, i.e. empties are filled with bit a3-1)
279 #define UDI_GFX_OPERATOR_SAL 16 // output = a1 <<< (a2 + v3) (empties filled with bit 0)
280 #define UDI_GFX_OPERATOR_AND 17 // output = a1 & a2
281 #define UDI_GFX_OPERATOR_OR 18 // output = a1 | a2 | v3
282 #define UDI_GFX_OPERATOR_NOT 19 // output = ~a1
283 #define UDI_GFX_OPERATOR_XOR 20 // output = a1 ^ a2 ^ v3
284 #define UDI_GFX_OPERATOR_NEG 21 // output = -a1
285 #define UDI_GFX_OPERATOR_SEG 22 // output = (a1 >> v2) & (2**v3-1) (select v3 bits starting from bit v2)
286 #define UDI_GFX_OPERATOR_RANGE 23 // output = (a1 > a2) ? a2 : ((a1 < a3) ? a3 : a1)
287 #define UDI_GFX_OPERATOR_CONST 24 // output = v1
288 #define UDI_GFX_OPERATOR_ATTR 25 // output = property[a1 + v2]
289 #define UDI_GFX_OPERATOR_SWITCH 26 // output = output[(a1 % v3) + v2]
290 #define UDI_GFX_OPERATOR_BUFFER 27 // output = buffer[a1][a2] (buffer is v3 bits per entry)
291 #define UDI_GFX_OPERATOR_X 28 // output = output x pixel
292 #define UDI_GFX_OPERATOR_Y 29 // output = output y pixel
293 #define UDI_GFX_OPERATOR_TX 30 // output = horizontal tile index belonging to output pixel
294 #define UDI_GFX_OPERATOR_TY 31 // output = vertical tile index belonging to output pixel
295 #define UDI_GFX_OPERATOR_TXOFF 32 // output = horizontal offset from start of tile
296 #define UDI_GFX_OPERATOR_TYOFF 33 // output = vertical offset from start of tile
297 #define UDI_GFX_OPERATOR_INPUT 34 // output = input engine[x][y] component v1
298 #define UDI_GFX_OPERATOR_DINPUT 35 // output = input engine[a1][a2] component v3
302 // Constant: UDI_GFX_PROVIDER_OPS_NUM
303 // the ops number used for the graphics driver
304 #define UDI_GFX_PROVIDER_OPS_NUM 1
306 // Constant: UDI_GFX_CLIENT_OPS_NUM
307 // the ops number used for the graphics application
308 #define UDI_GFX_CLIENT_OPS_NUM 2
310 // Structure: udi_gfx_bind_cb_t
311 // Contains the operations of a driver binding request
314 // The main control block
317 #define UDI_GFX_BIND_CB_NUM 1
319 // Function: udi_block_bind_req
320 // function pointer prototype for connecting to a block device
323 // cb - A pointer to a <udi_block_bind_cb_t>
325 typedef void udi_gfx_bind_req_op_t (udi_gfx_bind_cb_t *cb );
326 udi_gfx_bind_req_op_t udi_gfx_bind_req;
328 // Function: udi_gfx_bind_ack
329 // function pointer prototype for acknowledging a connection request
332 // cb - A pointer to a <udi_gfx_bind_cb_t>
333 // sockets - The number of addressable socket components
334 // engines - The number of addressable engine components
335 // status - The result of the bind operation
337 typedef void udi_gfx_bind_ack_op_t (udi_gfx_bind_cb_t *cb, udi_index_t sockets, udi_index_t engines, udi_status_t status );
338 udi_gfx_bind_ack_op_t udi_gfx_bind_ack;
340 // Function: udi_gfx_unbind_req
341 // function pointer prototype for disconnecting a block device
344 // cb - A pointer to a <udi_block_bind_cb_t>
346 typedef void udi_gfx_unbind_req_op_t (udi_gfx_bind_cb_t *cb );
347 udi_gfx_unbind_req_op_t udi_gfx_unbind_req;
349 // Function: udi_gfx_unbind_ack
350 // function pointer prototype for connecting to a block device
353 // cb - A pointer to a <udi_gfx_bind_cb_t>
355 typedef void udi_gfx_unbind_ack_op_t (udi_gfx_bind_cb_t *cb );
356 udi_gfx_unbind_ack_op_t udi_gfx_unbind_ack;
358 // Structure: udi_gfx_state_cb_t
359 // Contains the operations of a read/write transaction
362 // The main control block
364 udi_ubit32_t subsystem;
365 udi_ubit32_t attribute;
366 } udi_gfx_state_cb_t;
367 #define UDI_GFX_STATE_CB_NUM 2
369 // Function: udi_gfx_set_engine_req
370 // function pointer prototype for setting an engine state
373 // cb - A pointer to a <udi_gfx_state_cb_t>
375 typedef void udi_gfx_set_engine_req_op_t (udi_gfx_state_cb_t *cb, udi_ubit32_t value);
376 udi_gfx_set_engine_req_op_t udi_gfx_set_engine_req;
378 // Function: udi_gfx_set_connector_req
379 // function pointer prototype for setting an connector state
382 // cb - A pointer to a <udi_gfx_state_cb_t>
384 typedef void udi_gfx_set_connector_req_op_t (udi_gfx_state_cb_t *cb, udi_ubit32_t value);
385 udi_gfx_set_connector_req_op_t udi_gfx_set_connector_req;
387 // Function: udi_gfx_set_engine_ack
388 // function pointer prototype for setting an engine state
391 // cb - A pointer to a <udi_gfx_state_cb_t>
393 typedef void udi_gfx_set_engine_ack_op_t (udi_gfx_state_cb_t *cb );
394 udi_gfx_set_engine_ack_op_t udi_gfx_set_engine_ack;
396 // Function: udi_gfx_set_connector_ack
397 // function pointer prototype for setting an engine state
400 // cb - A pointer to a <udi_gfx_state_cb_t>
402 typedef void udi_gfx_set_connector_ack_op_t (udi_gfx_state_cb_t *cb );
403 udi_gfx_set_connector_ack_op_t udi_gfx_set_connector_ack;
405 // Function: udi_gfx_get_engine_req
406 // function pointer prototype for setting an engine state
409 // cb - A pointer to a <udi_gfx_state_cb_t>
411 typedef void udi_gfx_get_engine_req_op_t (udi_gfx_state_cb_t *cb );
412 udi_gfx_get_engine_req_op_t udi_gfx_get_engine_req;
414 // Function: udi_gfx_get_connector_req
415 // function pointer prototype for setting an connector state
418 // cb - A pointer to a <udi_gfx_state_cb_t>
420 typedef void udi_gfx_get_connector_req_op_t (udi_gfx_state_cb_t *cb );
421 udi_gfx_get_connector_req_op_t udi_gfx_get_connector_req;
423 // Function: udi_gfx_get_engine_ack
424 // function pointer prototype for setting an engine state
427 // cb - A pointer to a <udi_gfx_state_cb_t>
429 typedef void udi_gfx_get_engine_ack_op_t (udi_gfx_state_cb_t *cb, udi_ubit32_t value);
430 udi_gfx_get_engine_ack_op_t udi_gfx_get_engine_ack;
432 // Function: udi_gfx_get_connector_ack
433 // function pointer prototype for setting an engine state
436 // cb - A pointer to a <udi_gfx_state_cb_t>
438 typedef void udi_gfx_get_connector_ack_op_t (udi_gfx_state_cb_t *cb, udi_ubit32_t value);
439 udi_gfx_get_connector_ack_op_t udi_gfx_get_connector_ack;
442 // Structure: udi_gfx_range_cb_t
443 // Contains the operations of a range request transaction
446 // The main control block
448 udi_ubit32_t subsystem;
449 udi_ubit32_t attribute;
450 udi_buf_t * rangedata;
451 } udi_gfx_range_cb_t;
452 #define UDI_GFX_RANGE_CB_NUM 3
454 // Function: udi_gfx_range_engine_req
455 // function pointer prototype for getting an engine property range
458 // cb - A pointer to a <udi_gfx_range_cb_t>
460 typedef void udi_gfx_range_engine_req_op_t (udi_gfx_range_cb_t *cb );
461 udi_gfx_range_engine_req_op_t udi_gfx_range_engine_req;
463 // Function: udi_gfx_range_connector_req
464 // function pointer prototype for getting a connector property range
467 // cb - A pointer to a <udi_gfx_range_cb_t>
469 typedef void udi_gfx_range_connector_req_op_t (udi_gfx_range_cb_t *cb );
470 udi_gfx_range_connector_req_op_t udi_gfx_range_connector_req;
472 // Function: udi_gfx_range_engine_ack
473 // function pointer prototype for replying an engine property range
476 // cb - A pointer to a <udi_gfx_range_cb_t>
478 typedef void udi_gfx_range_engine_ack_op_t (udi_gfx_range_cb_t *cb );
479 udi_gfx_range_engine_ack_op_t udi_gfx_range_engine_ack;
481 // Function: udi_gfx_range_connector_ack
482 // function pointer prototype for replying a connector property range
485 // cb - A pointer to a <udi_gfx_range_cb_t>
487 typedef void udi_gfx_range_connector_ack_op_t (udi_gfx_range_cb_t *cb );
488 udi_gfx_range_connector_ack_op_t udi_gfx_range_connector_ack;
491 // Structure: udi_gfx_command_cb_t
492 // Contains the operations of a command sequence
495 // The main control block
497 udi_buf_t * commanddata;
498 } udi_gfx_command_cb_t;
499 #define UDI_GFX_COMMAND_CB_NUM 4
501 // Function: udi_gfx_command
502 // function pointer prototype for sending command data
505 // cb - A pointer to a <udi_gfx_command_cb_t>
507 typedef void udi_gfx_command_req_op_t (udi_gfx_command_cb_t *cb );
508 udi_gfx_command_req_op_t udi_gfx_command_req;
510 // Function: udi_gfx_command_ack
511 // function pointer prototype for sending command data
514 // cb - A pointer to a <udi_gfx_command_cb_t>
516 typedef void udi_gfx_command_ack_op_t (udi_gfx_command_cb_t *cb);
517 udi_gfx_command_ack_op_t udi_gfx_command_ack;
519 /* Structure: udi_gfx_provider_ops_t
520 The graphics metalanguage e*ntry points (provider side)
522 typedef const struct {
523 udi_channel_event_ind_op_t *channel_event_ind_op;
524 udi_gfx_bind_req_op_t *gfx_bind_req_op;
525 udi_gfx_unbind_req_op_t *gfx_unbind_req_op;
526 udi_gfx_set_connector_req_op_t *gfx_set_connector_req_op;
527 udi_gfx_set_engine_req_op_t *gfx_set_engine_req_op;
528 udi_gfx_get_connector_req_op_t *gfx_get_connector_req_op;
529 udi_gfx_get_engine_req_op_t *gfx_get_engine_req_op;
530 udi_gfx_range_connector_req_op_t *gfx_range_connector_req_op;
531 udi_gfx_range_engine_req_op_t *gfx_range_engine_req_op;
532 udi_gfx_command_req_op_t *gfx_command_op;
533 } udi_gfx_provider_ops_t;
535 /* Structure: udi_gfx_client_ops_t
536 * The graphics metalanguage entry points (client side)
538 typedef const struct {
539 udi_channel_event_ind_op_t *channel_event_ind_op;
540 udi_gfx_bind_ack_op_t *udi_gfx_bind_ack;
541 udi_gfx_unbind_ack_op_t *udi_gfx_unbind_ack;
542 udi_gfx_set_connector_ack_op_t *udi_gfx_set_connector_ack;
543 udi_gfx_set_engine_ack_op_t *udi_gfx_set_engine_ack;
544 udi_gfx_get_connector_ack_op_t *udi_gfx_get_connector_ack;
545 udi_gfx_get_engine_ack_op_t *udi_gfx_get_engine_ack;
546 udi_gfx_range_connector_ack_op_t *udi_gfx_range_connector_ack;
547 udi_gfx_range_engine_ack_op_t *udi_gfx_range_engine_ack;
548 udi_gfx_command_ack_op_t *udi_gfx_command_ack;
549 } udi_gfx_client_ops_t;
554 void EngineReturnSimpleRange (int source, int index, int prop, int first, int last, int modulus);
555 void ConnectorReturnSimpleRange (int source, int index, int prop, int first, int last, int modulus);
556 void EngineReturnConstantRange (int source, int index, int prop, int value);
557 void ConnectorReturnConstantRange (int source, int index, int prop, int value);
558 void EngineReturnBooleanRange (int source, int index, int prop, int value1, int value2);
559 void ConnectorReturnBooleanRange (int source, int index, int prop, int value1, int value2);