KallistiOS git master
Independent SDK for the Sega Dreamcast
Loading...
Searching...
No Matches
pvr.h
Go to the documentation of this file.
1/* KallistiOS ##version##
2
3 dc/pvr.h
4 Copyright (C) 2002 Megan Potter
5 Copyright (C) 2014 Lawrence Sebald
6 Copyright (C) 2023 Ruslan Rostovtsev
7
8 Low-level PVR 3D interface for the DC
9*/
10
11/** \file dc/pvr.h
12 \brief Low-level PVR (3D hardware) interface.
13 \ingroup pvr
14
15 This file provides support for using the PVR 3D hardware in the Dreamcast.
16 Note that this does not handle any sort of perspective transformations or
17 anything of the like. This is just a very thin wrapper around the actual
18 hardware support.
19
20 This file is used for pretty much everything related to the PVR, from memory
21 management to actual primitive rendering.
22
23 \note
24 This API does \a not handle any sort of transformations
25 (including perspective!) so for that, you should look to KGL.
26
27 \author Megan Potter
28 \author Roger Cattermole
29 \author Paul Boese
30 \author Brian Paul
31 \author Lawrence Sebald
32 \author Benoit Miller
33 \author Ruslan Rostovtsev
34*/
35
36#ifndef __DC_PVR_H
37#define __DC_PVR_H
38
39#include <kos/cdefs.h>
40__BEGIN_DECLS
41
42#include <stdalign.h>
43#include <stdbool.h>
44#include <stdint.h>
45
46#include <dc/memory.h>
47#include <dc/sq.h>
48#include <kos/img.h>
49#include <kos/regfield.h>
50
51/* Note: This file also #includes headers from dc/pvr/. They are mostly
52 at the bottom of the file to be able to use types defined throughout. */
53
54#include "pvr/pvr_mem.h"
55#include "pvr/pvr_header.h"
56
57/** \defgroup pvr PowerVR API
58 \brief Low-level PowerVR GPU Driver.
59 \ingroup video
60*/
61
62/* Data types ********************************************************/
63
64/** \defgroup pvr_lists Polygon Lists
65 \brief Types pertaining to PVR list types: opaque, pt, tr, etc
66 \ingroup pvr
67*/
68
69/** \defgroup pvr_geometry Geometry
70 \brief PVR API for managing scene geometry
71 \ingroup pvr
72*/
73
74/** \defgroup pvr_primitives Primitives
75 \brief Polygon and sprite management
76 \ingroup pvr_geometry
77*/
78
79/** \defgroup pvr_ctx Contexts
80 \brief User-friendly intermittent primitive representation
81 \ingroup pvr_primitives
82*/
83
84/** \defgroup pvr_mip_bias Mipmap Bias Modes
85 \brief Mipmap bias modes for PowerVR primitive contexts
86 \ingroup pvr_ctx_texture
87
88 @{
89*/
108/** @} */
109
110/** \defgroup pvr_uv_flip U/V Flip Mode
111 \brief Enable or disable U/V flipping on the PVR
112 \ingroup pvr_ctx_texture
113
114 These flags determine what happens when U/V coordinate values exceed 1.0.
115 In any of the flipped cases, the specified coordinate value will flip around
116 after 1.0, essentially mirroring the image. So, if you displayed an image
117 with a U coordinate of 0.0 on the left hand side and 2.0 on the right hand
118 side with U flipping turned on, you'd have an image that was displayed twice
119 as if mirrored across the middle. This mirroring behavior happens at every
120 unit boundary (so at 2.0 it returns to normal, at 3.0 it flips, etc).
121
122 The default case is to disable mirroring. In addition, clamping of the U/V
123 coordinates by PVR_UVCLAMP_U, PVR_UVCLAMP_V, or PVR_UVCLAMP_UV will disable
124 the mirroring behavior.
125 @{
126*/
127typedef enum pvr_uv_flip {
128 PVR_UVFLIP_NONE, /**< No flipped coordinates */
129 PVR_UVFLIP_V, /**< Flip V only */
130 PVR_UVFLIP_U, /**< Flip U only */
131 PVR_UVFLIP_UV /**< Flip U and V */
133/** @} */
134
135/** \defgroup pvr_uv_clamp U/V Clamp Mode
136 \brief Enable or disable clamping of U/V on the PVR
137 \ingroup pvr_ctx_texture
138
139 These flags determine whether clamping will be applied to U/V coordinate
140 values that exceed 1.0. If enabled, these modes will explicitly override the
141 flip/mirroring modes (PVR_UVFLIP_U, PVR_UVFLIP_V, and PVR_UVFLIP_UV), and
142 will instead ensure that the coordinate(s) in question never exceed 1.0.
143 @{
144*/
145typedef enum pvr_uv_clamp {
146 PVR_UVCLAMP_NONE, /**< Disable clamping */
147 PVR_UVCLAMP_V, /**< Clamp V only */
148 PVR_UVCLAMP_U, /**< Clamp U only */
149 PVR_UVCLAMP_UV /**< Clamp U and V */
151/** @} */
152
153/** \brief PVR polygon context.
154 \ingroup pvr_ctx
155
156 You should use this more human readable format for specifying your polygon
157 contexts, and then compile them into polygon headers when you are ready to
158 start using them.
159
160 This has embedded structures in it for two reasons; the first reason is to
161 make it easier for me to add new stuff later without breaking existing code.
162 The second reason is to make it more readable and usable.
163
164 Unfortunately, it seems that Doxygen chokes up a little bit on this
165 structure, and others like it. The documentation should still be mostly
166 understandable though...
167
168 \headerfile dc/pvr.h
169*/
170typedef struct {
171 pvr_list_t list_type; /**< \brief Primitive list */
172 struct {
173 bool alpha; /**< \brief Enable alpha outside modifier */
174 bool shading; /**< \brief Enable gourad shading */
175 pvr_fog_type_t fog_type; /**< \brief Fog type outside modifier */
176 pvr_cull_mode_t culling; /**< \brief Culling mode */
177 bool color_clamp; /**< \brief Enable color clamping outside modifer */
178 pvr_clip_mode_t clip_mode; /**< \brief Clipping mode */
179 bool modifier_mode; /**< \brief True normal; false: cheap shadow */
180 bool specular; /**< \brief Enable offset color outside modifier */
181 bool alpha2; /**< \brief Enable alpha inside modifier */
182 pvr_fog_type_t fog_type2; /**< \brief Fog type inside modifier */
183 bool color_clamp2; /**< \brief Enable color clamping inside modifer */
184 pvr_strip_len_t strip_len; /**< \brief Max triangles per strip piece stored by the TA
185 (defaults to PVR_STRIP_LEN_2) */
186 } gen; /**< \brief General parameters */
187 struct {
188 pvr_blend_mode_t src; /**< \brief Source blending mode outside modifier */
189 pvr_blend_mode_t dst; /**< \brief Dest blending mode outside modifier */
190 bool src_enable; /**< \brief Source blending enable outside modifier */
191 bool dst_enable; /**< \brief Dest blending enable outside modifier */
192 pvr_blend_mode_t src2; /**< \brief Source blending mode inside modifier */
193 pvr_blend_mode_t dst2; /**< \brief Dest blending mode inside modifier */
194 bool src_enable2; /**< \brief Source blending mode inside modifier */
195 bool dst_enable2; /**< \brief Dest blending mode inside modifier */
196 } blend; /**< \brief Blending parameters */
197 struct {
198 pvr_color_fmts_t color; /**< \brief Color format in vertex */
199 bool uv; /**< \brief True: 16-bit floating-point U/Vs; False: 32-bit */
200 bool modifier; /**< \brief Enable modifier effects */
201 } fmt; /**< \brief Format control */
202 struct {
203 pvr_depthcmp_mode_t comparison; /**< \brief Depth comparison mode */
204 bool write; /**< \brief Enable depth writes */
205 } depth; /**< \brief Depth comparison/write modes */
206 struct {
207 bool enable; /**< \brief Enable/disable texturing */
208 pvr_filter_mode_t filter; /**< \brief Filtering mode */
209 bool mipmap; /**< \brief Enable/disable mipmaps */
210 pvr_mip_bias_t mipmap_bias; /**< \brief Mipmap bias */
211 pvr_uv_flip_t uv_flip; /**< \brief Enable/disable U/V flipping */
212 pvr_uv_clamp_t uv_clamp; /**< \brief Enable/disable U/V clamping */
213 bool alpha; /**< \brief True to _disable_ texture alpha */
214 pvr_txr_shading_mode_t env; /**< \brief Texture color contribution */
215 int width; /**< \brief Texture width (requires a power of 2) */
216 int height; /**< \brief Texture height (requires a power of 2) */
217 int format; /**< \brief Texture format
218 \see pvr_txr_fmts */
219 pvr_ptr_t base; /**< \brief Texture pointer */
220 } txr, /**< \brief Texturing params outside modifier */
221 txr2; /**< \brief Texturing params inside modifier */
223
224/** \brief PVR sprite context.
225 \ingroup pvr_ctx
226
227 You should use this more human readable format for specifying your sprite
228 contexts, and then compile them into sprite headers when you are ready to
229 start using them.
230
231 Unfortunately, it seems that Doxygen chokes up a little bit on this
232 structure, and others like it. The documentation should still be mostly
233 understandable though...
234
235 \headerfile dc/pvr.h
236*/
237typedef struct {
238 pvr_list_t list_type; /**< \brief Primitive list */
239 struct {
240 bool alpha; /**< \brief Enable alpha */
241 pvr_fog_type_t fog_type; /**< \brief Fog type */
242 pvr_cull_mode_t culling; /**< \brief Culling mode */
243 bool color_clamp; /**< \brief Enable color clamp */
244 pvr_clip_mode_t clip_mode; /**< \brief Clipping mode */
245 bool specular; /**< \brief Enable offset color */
246 } gen; /**< \brief General parameters */
247 struct {
248 pvr_blend_mode_t src; /**< \brief Source blending mode */
249 pvr_blend_mode_t dst; /**< \brief Dest blending mode */
250 bool src_enable; /**< \brief Source blending enable */
251 bool dst_enable; /**< \brief Dest blending enable */
252 } blend;
253 struct {
254 pvr_depthcmp_mode_t comparison; /**< \brief Depth comparison mode */
255 bool write; /**< \brief Enable depth writes */
256 } depth; /**< \brief Depth comparison/write modes */
257 struct {
258 bool enable; /**< \brief Enable/disable texturing */
259 pvr_filter_mode_t filter; /**< \brief Filtering mode */
260 bool mipmap; /**< \brief Enable/disable mipmaps */
261 pvr_mip_bias_t mipmap_bias; /**< \brief Mipmap bias */
262 pvr_uv_flip_t uv_flip; /**< \brief Enable/disable U/V flipping */
263 pvr_uv_clamp_t uv_clamp; /**< \brief Enable/disable U/V clamping */
264 bool alpha; /**< \brief True to _disable_ texture alpha */
265 pvr_txr_shading_mode_t env; /**< \brief Texture color contribution */
266 int width; /**< \brief Texture width (requires a power of 2) */
267 int height; /**< \brief Texture height (requires a power of 2) */
268 int format; /**< \brief Texture format
269 \see pvr_txr_fmts */
270 pvr_ptr_t base; /**< \brief Texture pointer */
271 } txr; /**< \brief Texturing params */
273
274/* Constants for the above structure; thanks to Benoit Miller for these */
275
276/** \defgroup pvr_ctx_attrib Attributes
277 \brief PVR primitive context attributes
278 \ingroup pvr_ctx
279*/
280
281/** \defgroup pvr_ctx_depth Depth
282 \brief Depth attributes for PVR polygon contexts
283 \ingroup pvr_ctx_attrib
284*/
285
286/** \defgroup pvr_ctx_texture Texture
287 \brief Texture attributes for PVR polygon contexts
288 \ingroup pvr_ctx_attrib
289*/
290
291/** \defgroup pvr_ctx_color Color
292 \brief Color attributes for PowerVR primitive contexts
293 \ingroup pvr_ctx_attrib
294*/
295
296/** \defgroup pvr_txr_fmts Formats
297 \brief PowerVR texture formats
298 \ingroup pvr_txr_mgmt
299
300 These are the texture formats that the PVR supports. Note that some of
301 these, you can OR together with other values.
302
303 @{
304*/
305#define PVR_TXRFMT_NONE 0 /**< \brief No texture */
306#define PVR_TXRFMT_VQ_DISABLE (0 << 30) /**< \brief Not VQ encoded */
307#define PVR_TXRFMT_VQ_ENABLE (1 << 30) /**< \brief VQ encoded */
308#define PVR_TXRFMT_ARGB1555 (0 << 27) /**< \brief 16-bit ARGB1555 */
309#define PVR_TXRFMT_RGB565 (1 << 27) /**< \brief 16-bit RGB565 */
310#define PVR_TXRFMT_ARGB4444 (2 << 27) /**< \brief 16-bit ARGB4444 */
311#define PVR_TXRFMT_YUV422 (3 << 27) /**< \brief YUV422 format */
312#define PVR_TXRFMT_BUMP (4 << 27) /**< \brief Bumpmap format */
313#define PVR_TXRFMT_PAL4BPP (5 << 27) /**< \brief 4BPP paletted format */
314#define PVR_TXRFMT_PAL8BPP (6 << 27) /**< \brief 8BPP paletted format */
315#define PVR_TXRFMT_TWIDDLED (0 << 26) /**< \brief Texture is twiddled */
316#define PVR_TXRFMT_NONTWIDDLED (1 << 26) /**< \brief Texture is not twiddled */
317#define PVR_TXRFMT_POW2_STRIDE (0 << 25) /**< \brief Stride is a power-of-two */
318#define PVR_TXRFMT_X32_STRIDE (1 << 25) /**< \brief Stride is multiple of 32 */
319
320/* Compat. */
321static const uint32_t PVR_TXRFMT_NOSTRIDE __depr("Please use PVR_TXRFMT_POW2_STRIDE.") = PVR_TXRFMT_POW2_STRIDE;
322static const uint32_t PVR_TXRFMT_STRIDE __depr("Please use PVR_TXRFMT_X32_STRIDE. Note this may cause breakage as PVR_TXRFMT_STRIDE was never working correctly." ) = PVR_TXRFMT_X32_STRIDE;
323
324/* OR one of these into your texture format if you need it. Note that
325 these coincide with the twiddled/stride bits, so you can't have a
326 non-twiddled/strided texture that's paletted! */
327
328/** \brief 8BPP palette selector
329
330 \param x The palette index */
331#define PVR_TXRFMT_8BPP_PAL(x) ((x) << 25)
332
333/** \brief 4BPP palette selector
334
335 \param x The palette index */
336#define PVR_TXRFMT_4BPP_PAL(x) ((x) << 21)
337/** @} */
338
339/** \defgroup pvr_ctx_modvol Modifier Volumes
340 \brief PowerVR modifier volume polygon context attributes
341 \ingroup pvr_ctx_attrib
342*/
343
344/** \defgroup pvr_mod_modes Modes
345 \brief Modifier volume modes for PowerVR primitive contexts
346 \ingroup pvr_ctx_modvol
347
348 All triangles in a single modifier volume should be of the other poly type,
349 except for the last one. That should be either of the other two types,
350 depending on whether you want an inclusion or exclusion volume.
351
352 @{
353*/
354#define PVR_MODIFIER_OTHER_POLY 0 /**< \brief Not the last polygon in the volume */
355#define PVR_MODIFIER_INCLUDE_LAST_POLY 1 /**< \brief Last polygon, inclusion volume */
356#define PVR_MODIFIER_EXCLUDE_LAST_POLY 2 /**< \brief Last polygon, exclusion volume */
357/** @} */
358
359/** \defgroup pvr_primitives_headers Headers
360 \brief Compiled headers for polygons and sprites
361 \ingroup pvr_primitives
362
363 @{
364*/
365
366/** \brief PVR polygon header with intensity color.
367
368 This is the equivalent of pvr_poly_hdr_t, but for use with intensity color.
369
370 \headerfile dc/pvr.h
371*/
372#define pvr_poly_ic_hdr pvr_poly_hdr
374
375/** \brief PVR polygon header to be used with modifier volumes.
376
377 This is the equivalent of a pvr_poly_hdr_t for use when a polygon is to be
378 used with modifier volumes.
379
380 \headerfile dc/pvr.h
381*/
382#define pvr_poly_mod_hdr pvr_poly_hdr
384
385/** \brief PVR polygon header specifically for sprites.
386
387 This is the equivalent of a pvr_poly_hdr_t for use when a quad/sprite is to
388 be rendered. Note that the color data is here, not in the vertices.
389
390 \headerfile dc/pvr.h
391*/
392#define pvr_sprite_hdr pvr_poly_hdr
394
395/** \brief Modifier volume header.
396
397 This is the header that should be submitted when dealing with setting a
398 modifier volume.
399
400 \headerfile dc/pvr.h
401*/
402#define pvr_mod_hdr pvr_poly_hdr
404/** @} */
405
406/** \defgroup pvr_vertex_types Vertices
407 \brief PowerVR vertex types
408 \ingroup pvr_geometry
409
410 @{
411*/
412
413/** \brief Generic PVR vertex type.
414
415 The PVR chip itself supports many more vertex types, but this is the main
416 one that can be used with both textured and non-textured polygons, and is
417 fairly fast.
418
419 \headerfile dc/pvr.h
420*/
421typedef struct pvr_vertex {
422 alignas(32)
423 uint32_t flags; /**< \brief TA command (vertex flags) */
424 float x; /**< \brief X coordinate */
425 float y; /**< \brief Y coordinate */
426 float z; /**< \brief Z coordinate */
427 union {
428 struct {
429 float u; /**< \brief Texture U coordinate */
430 float v; /**< \brief Texture V coordinate */
431 };
432 struct {
433 uint32_t argb0; /**< \brief Vertex color when modified, outside area */
434 uint32_t argb1; /**< \brief Vertex color when modified, inside area */
435 };
436 };
437 uint32_t argb; /**< \brief Vertex color */
438 uint32_t oargb; /**< \brief Vertex offset color */
440
441/** \brief PVR vertex type: Non-textured, packed color, affected by modifier
442 volume.
443
444 This vertex type has two copies of colors. The second color is used when
445 enclosed within a modifier volume.
446
447 \headerfile dc/pvr.h
448*/
449typedef struct pvr_vertex_pcm {
450 alignas(32)
451 uint32_t flags; /**< \brief TA command (vertex flags) */
452 float x; /**< \brief X coordinate */
453 float y; /**< \brief Y coordinate */
454 float z; /**< \brief Z coordinate */
455 uint32_t argb0; /**< \brief Vertex color (outside volume) */
456 uint32_t argb1; /**< \brief Vertex color (inside volume) */
457 uint32_t d1; /**< \brief Dummy value */
458 uint32_t d2; /**< \brief Dummy value */
460
461/** \brief PVR vertex type: Textured, packed color, affected by modifier volume.
462
463 Note that this vertex type has two copies of colors, offset colors, and
464 texture coords. The second set of texture coords, colors, and offset colors
465 are used when enclosed within a modifier volume.
466
467 \headerfile dc/pvr.h
468*/
469typedef struct pvr_vertex_tpcm {
470 alignas(32)
471 uint32_t flags; /**< \brief TA command (vertex flags) */
472 float x; /**< \brief X coordinate */
473 float y; /**< \brief Y coordinate */
474 float z; /**< \brief Z coordinate */
475 float u0; /**< \brief Texture U coordinate (outside) */
476 float v0; /**< \brief Texture V coordinate (outside) */
477 uint32_t argb0; /**< \brief Vertex color (outside) */
478 uint32_t oargb0; /**< \brief Vertex offset color (outside) */
479 float u1; /**< \brief Texture U coordinate (inside) */
480 float v1; /**< \brief Texture V coordinate (inside) */
481 uint32_t argb1; /**< \brief Vertex color (inside) */
482 uint32_t oargb1; /**< \brief Vertex offset color (inside) */
483 uint32_t d1; /**< \brief Dummy value */
484 uint32_t d2; /**< \brief Dummy value */
485 uint32_t d3; /**< \brief Dummy value */
486 uint32_t d4; /**< \brief Dummy value */
488
489/** \brief PVR vertex type: Textured sprite.
490
491 This vertex type is to be used with the sprite polygon header and the sprite
492 related commands to draw textured sprites. Note that there is no fourth Z
493 coordinate. I suppose it just gets interpolated?
494
495 The U/V coordinates in here are in the 16-bit per coordinate form. Also,
496 like the fourth Z value, there is no fourth U or V, so it must get
497 interpolated from the others.
498
499 \headerfile dc/pvr.h
500*/
501typedef struct pvr_sprite_txr {
502 alignas(32)
503 uint32_t flags; /**< \brief TA command (vertex flags) */
504 float ax; /**< \brief First X coordinate */
505 float ay; /**< \brief First Y coordinate */
506 float az; /**< \brief First Z coordinate */
507 float bx; /**< \brief Second X coordinate */
508 float by; /**< \brief Second Y coordinate */
509 float bz; /**< \brief Second Z coordinate */
510 float cx; /**< \brief Third X coordinate */
511 float cy; /**< \brief Third Y coordinate */
512 float cz; /**< \brief Third Z coordinate */
513 float dx; /**< \brief Fourth X coordinate */
514 float dy; /**< \brief Fourth Y coordinate */
515 uint32_t dummy; /**< \brief Dummy value */
516 uint32_t auv; /**< \brief First U/V texture coordinates */
517 uint32_t buv; /**< \brief Second U/V texture coordinates */
518 uint32_t cuv; /**< \brief Third U/V texture coordinates */
520
521/** \brief PVR vertex type: Untextured sprite.
522
523 This vertex type is to be used with the sprite polygon header and the sprite
524 related commands to draw untextured sprites (aka, quads).
525*/
526typedef struct pvr_sprite_col {
527 alignas(32)
528 uint32_t flags; /**< \brief TA command (vertex flags) */
529 float ax; /**< \brief First X coordinate */
530 float ay; /**< \brief First Y coordinate */
531 float az; /**< \brief First Z coordinate */
532 float bx; /**< \brief Second X coordinate */
533 float by; /**< \brief Second Y coordinate */
534 float bz; /**< \brief Second Z coordinate */
535 float cx; /**< \brief Third X coordinate */
536 float cy; /**< \brief Third Y coordinate */
537 float cz; /**< \brief Third Z coordinate */
538 float dx; /**< \brief Fourth X coordinate */
539 float dy; /**< \brief Fourth Y coordinate */
540 uint32_t d1; /**< \brief Dummy value */
541 uint32_t d2; /**< \brief Dummy value */
542 uint32_t d3; /**< \brief Dummy value */
543 uint32_t d4; /**< \brief Dummy value */
545
546/** \brief PVR vertex type: Modifier volume.
547
548 This vertex type is to be used with the modifier volume header to specify
549 triangular modifier areas.
550*/
551typedef struct pvr_modifier_vol {
552 alignas(32)
553 uint32_t flags; /**< \brief TA command (vertex flags) */
554 float ax; /**< \brief First X coordinate */
555 float ay; /**< \brief First Y coordinate */
556 float az; /**< \brief First Z coordinate */
557 float bx; /**< \brief Second X coordinate */
558 float by; /**< \brief Second Y coordinate */
559 float bz; /**< \brief Second Z coordinate */
560 float cx; /**< \brief Third X coordinate */
561 float cy; /**< \brief Third Y coordinate */
562 float cz; /**< \brief Third Z coordinate */
563 uint32_t d1; /**< \brief Dummy value */
564 uint32_t d2; /**< \brief Dummy value */
565 uint32_t d3; /**< \brief Dummy value */
566 uint32_t d4; /**< \brief Dummy value */
567 uint32_t d5; /**< \brief Dummy value */
568 uint32_t d6; /**< \brief Dummy value */
570
571/** @} */
572
573/** \defgroup pvr_commands TA Command Values
574 \brief Command values for submitting data to the TA
575 \ingroup pvr_primitives_headers
576
577 These are are appropriate values for TA commands. Use whatever goes with the
578 primitive type you're using.
579
580 @{
581*/
582#define PVR_CMD_POLYHDR 0x80840000 /**< \brief PVR polygon header.
583Striplength set to 2 */
584#define PVR_CMD_VERTEX 0xe0000000 /**< \brief PVR vertex data */
585#define PVR_CMD_VERTEX_EOL 0xf0000000 /**< \brief PVR vertex, end of strip */
586#define PVR_CMD_USERCLIP 0x20000000 /**< \brief PVR user clipping area */
587#define PVR_CMD_MODIFIER 0x80000000 /**< \brief PVR modifier volume */
588#define PVR_CMD_SPRITE 0xA0000000 /**< \brief PVR sprite header */
589/** @} */
590
591/** \defgroup pvr_bitmasks Constants and Masks
592 \brief Polygon header constants and masks
593 \ingroup pvr_primitives_headers
594
595 Note that thanks to the arrangement of constants, this is mainly a matter of
596 bit shifting to compile headers...
597
598 @{
599*/
600#define PVR_TA_CMD_TYPE GENMASK(26, 24)
601#define PVR_TA_CMD_STRIPLEN GENMASK(19, 18)
602#define PVR_TA_CMD_USERCLIP GENMASK(17, 16)
603#define PVR_TA_CMD_MODIFIER BIT(7)
604#define PVR_TA_CMD_MODIFIERMODE BIT(6)
605#define PVR_TA_CMD_CLRFMT GENMASK(5, 4)
606#define PVR_TA_CMD_TXRENABLE BIT(3)
607#define PVR_TA_CMD_SPECULAR BIT(2)
608#define PVR_TA_CMD_SHADE BIT(1)
609#define PVR_TA_CMD_UVFMT BIT(0)
610#define PVR_TA_PM1_DEPTHCMP GENMASK(31, 29)
611#define PVR_TA_PM1_CULLING GENMASK(28, 27)
612#define PVR_TA_PM1_DEPTHWRITE BIT(26)
613#define PVR_TA_PM1_TXRENABLE BIT(25)
614#define PVR_TA_PM1_MODIFIERINST GENMASK(30, 29)
615#define PVR_TA_PM2_SRCBLEND GENMASK(31, 29)
616#define PVR_TA_PM2_DSTBLEND GENMASK(28, 26)
617#define PVR_TA_PM2_SRCENABLE BIT(25)
618#define PVR_TA_PM2_DSTENABLE BIT(24)
619#define PVR_TA_PM2_FOG GENMASK(23, 22)
620#define PVR_TA_PM2_CLAMP BIT(21)
621#define PVR_TA_PM2_ALPHA BIT(20)
622#define PVR_TA_PM2_TXRALPHA BIT(19)
623#define PVR_TA_PM2_UVFLIP GENMASK(18, 17)
624#define PVR_TA_PM2_UVCLAMP GENMASK(16, 15)
625#define PVR_TA_PM2_FILTER GENMASK(14, 13)
626#define PVR_TA_PM2_MIPBIAS GENMASK(11, 8)
627#define PVR_TA_PM2_TXRENV GENMASK(7, 6)
628#define PVR_TA_PM2_USIZE GENMASK(5, 3)
629#define PVR_TA_PM2_VSIZE GENMASK(2, 0)
630#define PVR_TA_PM3_MIPMAP BIT(31)
631#define PVR_TA_PM3_TXRFMT GENMASK(30, 21)
632/** @} */
633
634/* Initialization ****************************************************/
635/** \defgroup pvr_init Initialization
636 \brief Driver initialization and shutdown
637 \ingroup pvr
638
639 Initialization and shutdown: stuff you should only ever have to do
640 once in your program.
641*/
642
643/** \defgroup pvr_binsizes Primitive Bin Sizes
644 \brief Available sizes for primitive bins
645 \ingroup pvr_init
646 @{
647*/
648#define PVR_BINSIZE_0 0 /**< \brief 0-length (disables the list) */
649#define PVR_BINSIZE_8 8 /**< \brief 8-word (32-byte) length */
650#define PVR_BINSIZE_16 16 /**< \brief 16-word (64-byte) length */
651#define PVR_BINSIZE_32 32 /**< \brief 32-word (128-byte) length */
652/** @} */
653
654/** \brief PVR initialization structure
655 \ingroup pvr_init
656
657 This structure defines how the PVR initializes various parts of the system,
658 including the primitive bin sizes, the vertex buffer size, and whether
659 vertex DMA will be enabled.
660
661 You essentially fill one of these in, and pass it to pvr_init().
662
663 \headerfile dc/pvr.h
664 \sa pvr_default_params
665*/
666typedef struct {
667 /** \brief Bin sizes.
668
669 The bins go in the following order: opaque polygons, opaque modifiers,
670 translucent polygons, translucent modifiers, punch-thrus
671 */
672 int opb_sizes[5];
673
674 /** \brief Vertex buffer size (should be a nice round number) */
676
677 /** \brief Enable vertex DMA?
678
679 Set to non-zero if we want to enable vertex DMA mode. Note that if this
680 is set, then _all_ enabled lists need to have a vertex buffer assigned,
681 even if you never use that list for anything.
682 */
684
685 /** \brief Enable horizontal scaling?
686
687 Set to non-zero if horizontal scaling is to be enabled. By enabling this
688 setting and stretching your image to double the native screen width, you
689 can get horizontal full-screen anti-aliasing. */
691
692 /** \brief Disable translucent polygon autosort?
693
694 Set to non-zero to disable translucent polygon autosorting. By enabling
695 this setting, the PVR acts more like a traditional Z-buffered system
696 when rendering translucent polygons, meaning you must pre-sort them
697 yourself if you want them to appear in the right order. */
699
700
701 /** \brief OPB Overflow Count.
702
703 Preallocates this many extra OPBs (sets of tile bins), allowing the PVR
704 to use the extra space when there's too much geometry in the first OPB.
705
706 Increasing this value can eliminate artifacts where pieces of geometry
707 flicker in and out of existence along the tile boundaries. */
708
710
711 /** \brief Disable vertex buffer double-buffering.
712
713 Use only one single vertex buffer. This means that the PVR must finish
714 rendering before the Tile Accelerator is used to prepare a new frame;
715 but it allows using much smaller vertex buffers. */
717
719
720/** \brief PVR initialization structure defaults
721 \ingroup pvr_init
722
723 These are the default values for pvr_init_params_t used by pvr_init_defaults().
724
725 \sa pvr_init_defaults()
726*/
729 .vertex_buf_size = 512 * 1024,
730 .opb_overflow_count = 3
731};
732
733/** \brief Initialize the PVR chip to ready status.
734 \ingroup pvr_init
735
736 This function enables the specified lists and uses the specified parameters.
737 Note that bins and vertex buffers come from the texture memory pool, so only
738 allocate what you actually need. Expects that a 2D mode was initialized
739 already using the vid_* API.
740
741 \param params The set of parameters to initialize with
742 \retval 0 On success
743 \retval -1 If the PVR has already been initialized or the video
744 mode active is not suitable for 3D
745*/
747
748/** \brief Simple PVR initialization.
749 \ingroup pvr_init
750
751 This simpler function initializes the PVR using the default parameters defined in
752 pvr_default_params.
753
754 \retval 0 On success
755 \retval -1 If the PVR has already been initialized or the video
756 mode active is not suitable for 3D
757
758 \sa pvr_default_params
759*/
761
762/** \brief Shut down the PVR chip from ready status.
763 \ingroup pvr_init
764
765 This essentially leaves the video system in 2D mode as it was before the
766 init.
767
768 \retval 0 On success
769 \retval -1 If the PVR has not been initialized
770*/
771int pvr_shutdown(void);
772
773
774/* Scene rendering ***************************************************/
775/** \defgroup pvr_scene_mgmt Scene Submission
776 \brief PowerVR API for submitting scene geometry
777 \ingroup pvr
778
779 This API is used to submit triangle strips to the PVR via the TA
780 interface in the chip.
781
782 An important side note about the PVR is that all primitive types
783 must be submitted grouped together. If you have 10 polygons for each
784 list type, then the PVR must receive them via the TA by list type,
785 with a list delimiter in between.
786
787 So there are two modes you can use here. The first mode allows you to
788 submit data directly to the TA. Your data will be forwarded to the
789 chip for processing as it is fed to the PVR module. If your data
790 is easily sorted into the primitive types, then this is the fastest
791 mode for submitting data.
792
793 The second mode allows you to submit data via main-RAM vertex buffers,
794 which will be queued until the proper primitive type is active. In this
795 case, each piece of data is copied into the vertex buffer while the
796 wrong list is activated, and when the proper list becomes activated,
797 the data is all sent at once. Ideally this would be via DMA, right
798 now it is by store queues. This has the advantage of allowing you to
799 send data in any order and have the PVR functions resolve how it should
800 get sent to the hardware, but it is slower.
801
802 The nice thing is that any combination of these modes can be used. You
803 can assign a vertex buffer for any list, and it will be used to hold the
804 incoming vertex data until the proper list has come up. Or if the proper
805 list is already up, the data will be submitted directly. So if most of
806 your polygons are opaque, and you only have a couple of translucents,
807 you can set a small buffer to gather translucent data and then it will
808 get sent when you do a pvr_end_scene().
809
810 Thanks to Mikael Kalms for the idea for this API.
811
812 \note
813 Another somewhat subtle point that bears mentioning is that in the normal
814 case (interrupts enabled) an interrupt handler will automatically take
815 care of starting a frame rendering (after scene_finish()) and also
816 flipping pages when appropriate.
817*/
818
819/** \defgroup pvr_vertex_dma Vertex DMA
820 \brief Use the DMA to transfer inactive lists to the PVR
821 \ingroup pvr_scene_mgmt
822*/
823
824/** \brief Is vertex DMA enabled?
825 \ingroup pvr_vertex_dma
826
827 \return Non-zero if vertex DMA was enabled at init time
828*/
830
831/** \brief Setup a vertex buffer for one of the list types.
832 \ingroup pvr_list_mgmt
833
834 If the specified list type already has a vertex buffer, it will be replaced
835 by the new one.
836
837 \note
838 Each buffer should actually be twice as long as what you will need to hold
839 two frames worth of data).
840
841 \warning
842 You should generally not try to do this at any time besides before a frame
843 is begun, or Bad Things May Happen.
844
845 \param list The primitive list to set the buffer for.
846 \param buffer The location of the buffer in main RAM. This must be
847 aligned to a 32-byte boundary.
848 \param len The length of the buffer. This must be a multiple of
849 64, and must be at least 128 (even if you're not
850 using the list).
851
852 \return The old buffer location (if any)
853*/
854void *pvr_set_vertbuf(pvr_list_t list, void *buffer, size_t len);
855
856/** \brief Retrieve a pointer to the current output location in the DMA buffer
857 for the requested list.
858 \ingroup pvr_vertex_dma
859
860 Vertex DMA must globally be enabled for this to work. Data may be added to
861 this buffer by the user program directly; however, make sure to call
862 pvr_vertbuf_written() to notify the system of any such changes.
863
864 \param list The primitive list to get the buffer for.
865
866 \return The tail of that list's buffer.
867*/
869
870/** \brief Notify the PVR system that data have been written into the output
871 buffer for the given list.
872 \ingroup pvr_vertex_dma
873
874 This should always be done after writing data directly to these buffers or
875 it will get overwritten by other data.
876
877 \param list The primitive list that was modified.
878 \param amt Number of bytes written. Must be a multiple of 32.
879*/
881
882/** \brief Begin collecting data for a frame of 3D output to the off-screen
883 frame buffer.
884 \ingroup pvr_scene_mgmt
885
886 You must call this function (or pvr_scene_begin_rtt()) for ever frame of
887 output.
888*/
890
891/** \brief Begin collecting data for a frame of 3D output to the specified
892 texture.
893 \ingroup pvr_scene_mgmt
894 \deprecated Use pvr_scene_begin_rtt() instead.
895
896 This function currently only supports outputting at the same size as the
897 actual screen. Thus, make sure rx and ry are at least large enough for that.
898 For a 640x480 output, rx will generally be 1024 on input and ry 512, as
899 these are the smallest values that are powers of two and will hold the full
900 screen sized output.
901
902 \param txr The texture to render to.
903 \param rx Width of the texture buffer (in pixels).
904 \param ry Height of the texture buffer (in pixels).
905*/
906void pvr_scene_begin_txr(pvr_ptr_t txr, uint32_t *rx, uint32_t *ry)
907 __depr("pvr_scene_begin_txr() is deprecated. Use pvr_scene_begin_rtt().");
908
909/** \brief Begin collecting scene data for rendering into a texture target
910 with an explicit render size.
911 \ingroup pvr_scene_mgmt
912
913 This is the preferred render-to-texture API and does not require a
914 screen-sized backing texture. The PVR will render into a region of render_w
915 by render_h pixels, using stride_px pixels as the backing memory pitch.
916
917 render_w and render_h describe the area to draw. stride_px describes the
918 number of pixels between rows in memory and must be greater than or equal
919 to render_w. For the initial 16-bit render target implementation,
920 stride_px must also be a multiple of 4 pixels.
921
922 \note Initial support is intended for 16-bit render targets, matching the
923 deprecated pvr_scene_begin_txr() compatibility wrapper behavior.
924
925 \param txr The texture to render to.
926 \param render_w Width of the render area (in pixels).
927 \param render_h Height of the render area (in pixels).
928 \param stride_px Backing texture pitch (in pixels).
929
930 \retval 0 On success.
931 \retval -1 If the specified arguments are invalid.
932*/
933int pvr_scene_begin_rtt(pvr_ptr_t txr, uint32_t render_w,
934 uint32_t render_h, uint32_t stride_px);
935
936
937/** \defgroup pvr_list_mgmt Polygon Lists
938 \brief PVR API for managing list submission
939 \ingroup pvr_scene_mgmt
940*/
941
942/** \brief Begin collecting data for the given list type.
943 \ingroup pvr_list_mgmt
944
945 Lists do not have to be submitted in any particular order, but all types of
946 a list must be submitted at once (unless vertex DMA mode is enabled).
947
948 Note that there is no need to call this function in DMA mode unless you want
949 to make use of pvr_prim() for compatibility. This function will
950 automatically call pvr_list_finish() if a list is already opened before
951 opening the new list.
952
953 \param list The list to open.
954 \retval 0 On success.
955 \retval -1 If the specified list has already been closed.
956*/
958
959/** \brief End collecting data for the current list type.
960 \ingroup pvr_list_mgmt
961
962 Lists can never be opened again within a single frame once they have been
963 closed. Thus submitting a primitive that belongs in a closed list is
964 considered an error. Closing a list that is already closed is also an error.
965
966 Note that if you open a list but do not submit any primitives, a blank one
967 will be submitted to satisfy the hardware. If vertex DMA mode is enabled,
968 then this simply sets the current list pointer to no list, and none of the
969 above restrictions apply.
970
971 \retval 0 On success.
972 \retval -1 On error.
973*/
975
976/** \brief Submit a primitive of the current list type.
977 \ingroup pvr_list_mgmt
978
979 Note that any values submitted in this fashion will go directly to the
980 hardware without any sort of buffering, and submitting a primitive of the
981 wrong type will quite likely ruin your scene. Note that this also will not
982 work if you haven't begun any list types (i.e., all data is queued). If DMA
983 is enabled, the primitive will be appended to the end of the currently
984 selected list's buffer.
985
986 \warning
987 \p data must be 32-byte aligned!
988
989 \param data The primitive to submit.
990 \param size The length of the primitive, in bytes. Must be a
991 multiple of 32.
992
993 \retval 0 On success.
994 \retval -1 On error.
995*/
996int pvr_prim(const void *data, size_t size);
997
998/** \defgroup pvr_direct Direct Rendering
999 \brief API for using direct rendering with the PVR
1000 \ingroup pvr_scene_mgmt
1001
1002 @{
1003*/
1004
1005/** \cond */
1006extern uint32_t pvr_dr_addr;
1007/** \endcond */
1008
1009/** \brief Obtain the target address for Direct Rendering.
1010
1011 Note that you're not expected to pass any argument. The macro can take
1012 arguments for compatibility reasons and will ignore them.
1013
1014 \return A write-only destination address where a primitive
1015 should be written to get ready to submit it to the
1016 TA in DR mode.
1017*/
1018#define pvr_dr_target(...) __builtin_assume_aligned((void *)((pvr_dr_addr ^= 32)), 32)
1019
1020/** \brief Commit a primitive written into the Direct Rendering target address.
1021
1022 \param addr The address returned by pvr_dr_target(), after you
1023 have written the primitive to it.
1024*/
1025#define pvr_dr_commit(addr) sq_flush(addr)
1026
1027/** \brief Upload a 32-byte payload to the Tile Accelerator
1028
1029 Upload the given payload to the Tile Accelerator. The difference with the
1030 Direct Rendering approach above is that the Store Queues are not used, and
1031 therefore can be used for anything else.
1032
1033 \param data A pointer to the 32-byte payload.
1034 The pointer must be aligned to 8 bytes.
1035*/
1037
1038/** @} */
1039
1040/** \brief Submit a primitive of the given list type.
1041 \ingroup pvr_list_mgmt
1042
1043 Data will be queued in a vertex buffer, thus one must be available for the
1044 list specified (will be asserted by the code).
1045
1046 \param list The list to submit to.
1047 \param data The primitive to submit.
1048 \param size The size of the primitive in bytes. This must be a
1049 multiple of 32.
1050
1051 \retval 0 On success.
1052 \retval -1 On error.
1053*/
1054int pvr_list_prim(pvr_list_t list, const void *data, size_t size);
1055
1056/** \brief Flush the buffered data of the given list type to the TA.
1057 \ingroup pvr_list_mgmt
1058
1059 This function is currently not implemented, and calling it will result in an
1060 assertion failure. It is intended to be used later in a "hybrid" mode where
1061 both direct and DMA TA submission is possible.
1062
1063 \param list The list to flush.
1064
1065 \retval -1 On error (it is not possible to succeed).
1066*/
1068
1069/** \brief Call this after you have finished submitting all data for a frame.
1070 \ingroup pvr_scene_mgmt
1071
1072 Once this has been called, you can not submit any more data until one of the
1073 pvr_scene_begin() or pvr_scene_begin_rtt() functions is called again.
1074
1075 \retval 0 On success.
1076 \retval -1 On error (no scene started).
1077*/
1079
1080/** \brief Block the caller until the PVR system is ready for another frame to
1081 be submitted.
1082 \ingroup pvr_scene_mgmt
1083
1084 The PVR system allocates enough space for two frames: one in data collection
1085 mode, and another in rendering mode. If a frame is currently rendering, and
1086 another frame has already been closed, then the caller cannot do anything
1087 else until the rendering frame completes. Note also that the new frame
1088 cannot be activated except during a vertical blanking period, so this
1089 essentially waits until a rendered frame is complete and a vertical blank
1090 happens.
1091
1092 \retval 0 On success. A new scene can be started now.
1093 \retval -1 On error. Something is probably very wrong...
1094*/
1096
1097/** \brief Check if the PVR system is ready for another frame to be submitted.
1098 \ingroup pvr_scene_mgmt
1099
1100 \retval 0 If the PVR is ready for a new scene. You must call
1101 pvr_wait_ready() afterwards, before starting a new
1102 scene.
1103 \retval -1 If the PVR is not ready for a new scene yet.
1104*/
1106
1107/** \brief Block the caller until the PVR has finished rendering the previous
1108 frame.
1109 \ingroup pvr_scene_mgmt
1110
1111 This function can be used to wait until the PVR is done rendering a previous
1112 scene. This can be useful for instance to make sure that the PVR is done
1113 using textures that have to be updated, before updating those.
1114
1115 \retval 0 On success.
1116 \retval -1 On error. Something is probably very wrong...
1117*/
1119
1120
1121/* Primitive handling ************************************************/
1122
1123/** \defgroup pvr_primitives_compilation Compilation
1124 \brief API for compiling primitive contexts
1125 into headers
1126 \ingroup pvr_ctx
1127*/
1128
1129/** \brief Compile a polygon context into a polygon header.
1130 \ingroup pvr_primitives_compilation
1131
1132 This function compiles a pvr_poly_cxt_t into the form needed by the hardware
1133 for rendering. This is for use with normal polygon headers.
1134
1135 \param dst Where to store the compiled header.
1136 \param src The context to compile.
1137*/
1139
1140/** \defgroup pvr_ctx_init Initialization
1141 \brief Functions for initializing PVR polygon contexts
1142 \ingroup pvr_ctx
1143*/
1144
1145/** \brief Fill in a polygon context for non-textured polygons.
1146 \ingroup pvr_ctx_init
1147
1148 This function fills in a pvr_poly_cxt_t with default parameters appropriate
1149 for rendering a non-textured polygon in the given list.
1150
1151 \param dst Where to store the polygon context.
1152 \param list The primitive list to be used.
1153*/
1155
1156/** \brief Fill in a polygon context for a textured polygon.
1157 \ingroup pvr_ctx_init
1158
1159 This function fills in a pvr_poly_cxt_t with default parameters appropriate
1160 for rendering a textured polygon in the given list.
1161
1162 \param dst Where to store the polygon context.
1163 \param list The primitive list to be used.
1164 \param textureformat The format of the texture used.
1165 \param tw The width of the texture, in pixels.
1166 \param th The height of the texture, in pixels.
1167 \param textureaddr A pointer to the texture.
1168 \param filtering The type of filtering to use.
1169
1170 \see pvr_txr_fmts
1171*/
1173 int textureformat, int tw, int th, pvr_ptr_t textureaddr,
1174 pvr_filter_mode_t filtering);
1175
1176/** \brief Compile a sprite context into a sprite header.
1177 \ingroup pvr_primitives_compilation
1178
1179 This function compiles a pvr_sprite_cxt_t into the form needed by the
1180 hardware for rendering. This is for use with sprite headers.
1181
1182 \param dst Where to store the compiled header.
1183 \param src The context to compile.
1184*/
1186 const pvr_sprite_cxt_t *src);
1187
1188/** \brief Fill in a sprite context for non-textured sprites.
1189 \ingroup pvr_ctx_init
1190
1191 This function fills in a pvr_sprite_cxt_t with default parameters
1192 appropriate for rendering a non-textured sprite in the given list.
1193
1194 \param dst Where to store the sprite context.
1195 \param list The primitive list to be used.
1196*/
1198
1199/** \brief Fill in a sprite context for a textured sprite.
1200 \ingroup pvr_ctx_init
1201
1202 This function fills in a pvr_sprite_cxt_t with default parameters
1203 appropriate for rendering a textured sprite in the given list.
1204
1205 \param dst Where to store the sprite context.
1206 \param list The primitive list to be used.
1207 \param textureformat The format of the texture used.
1208 \param tw The width of the texture, in pixels.
1209 \param th The height of the texture, in pixels.
1210 \param textureaddr A pointer to the texture.
1211 \param filtering The type of filtering to use.
1212
1213 \see pvr_txr_fmts
1214*/
1216 int textureformat, int tw, int th, pvr_ptr_t textureaddr,
1217 pvr_filter_mode_t filtering);
1218
1219/** \brief Create a modifier volume header.
1220 \ingroup pvr_primitives_compilation
1221
1222 This function fills in a modifier volume header with the parameters
1223 specified. Note that unlike for polygons and sprites, there is no context
1224 step for modifiers.
1225
1226 \param dst Where to store the modifier header.
1227 \param list The primitive list to be used.
1228 \param mode The mode for this modifier.
1229 \param cull The culling mode to use.
1230
1231 \see pvr_mod_modes
1232 \see pvr_cull_modes
1233*/
1235 uint32_t cull);
1236
1237/** \brief Compile a polygon context into a polygon header that is affected by
1238 modifier volumes.
1239 \ingroup pvr_primitives_compilation
1240
1241 This function works pretty similarly to pvr_poly_compile(), but compiles
1242 into the header type that is affected by a modifier volume. The context
1243 should have been created with either pvr_poly_cxt_col_mod() or
1244 pvr_poly_cxt_txr_mod().
1245
1246 \param dst Where to store the compiled header.
1247 \param src The context to compile.
1248*/
1250
1251/** \brief Fill in a polygon context for non-textured polygons affected by a
1252 modifier volume.
1253 \ingroup pvr_ctx_init
1254
1255 This function fills in a pvr_poly_cxt_t with default parameters appropriate
1256 for rendering a non-textured polygon in the given list that will be affected
1257 by modifier volumes.
1258
1259 \param dst Where to store the polygon context.
1260 \param list The primitive list to be used.
1261*/
1263
1264/** \brief Fill in a polygon context for a textured polygon affected by
1265 modifier volumes.
1266 \ingroup pvr_ctx_init
1267
1268 This function fills in a pvr_poly_cxt_t with default parameters appropriate
1269 for rendering a textured polygon in the given list and being affected by
1270 modifier volumes.
1271
1272 \param dst Where to store the polygon context.
1273 \param list The primitive list to be used.
1274 \param textureformat The format of the texture used (outside).
1275 \param tw The width of the texture, in pixels (outside).
1276 \param th The height of the texture, in pixels (outside).
1277 \param textureaddr A pointer to the texture (outside).
1278 \param filtering The type of filtering to use (outside).
1279 \param textureformat2 The format of the texture used (inside).
1280 \param tw2 The width of the texture, in pixels (inside).
1281 \param th2 The height of the texture, in pixels (inside).
1282 \param textureaddr2 A pointer to the texture (inside).
1283 \param filtering2 The type of filtering to use (inside).
1284
1285 \see pvr_txr_fmts
1286*/
1288 int textureformat, int tw, int th,
1289 pvr_ptr_t textureaddr, pvr_filter_mode_t filtering,
1290 int textureformat2, int tw2, int th2,
1291 pvr_ptr_t textureaddr2, pvr_filter_mode_t filtering2);
1292
1293/** \brief Get a pointer to the front buffer.
1294 \ingroup pvr_txr_mgmt
1295
1296 This function can be used to retrieve a pointer to the front buffer, aka.
1297 the last fully rendered buffer that is either being displayed right now,
1298 or is queued to be displayed.
1299
1300 Note that the frame buffers lie in 32-bit memory, while textures lie in
1301 64-bit memory. The address returned will point to 64-bit memory, but the
1302 front buffer cannot be used directly as a regular texture.
1303
1304 \return A pointer to the front buffer.
1305*/
1307
1308/** \brief Get a pointer to the back buffer.
1309 \ingroup pvr_txr_mgmt
1310
1311 This function can be used to retrieve a pointer to the back buffer, aka.
1312 the frame buffer that will be rendered to.
1313
1314 Note that the frame buffers lie in 32-bit memory, while textures lie in
1315 64-bit memory. The address returned will point to 64-bit memory, but the
1316 back buffer cannot be used directly as a regular texture.
1317
1318 \return A pointer to the back buffer.
1319*/
1321
1322/*********************************************************************/
1323
1324#include "pvr/pvr_regs.h"
1325#include "pvr/pvr2.h"
1326#include "pvr/pvr_misc.h"
1327#include "pvr/pvr_dma.h"
1328#include "pvr/pvr_fog.h"
1329#include "pvr/pvr_pal.h"
1330#include "pvr/pvr_txr.h"
1331#include "pvr/pvr_legacy.h"
1332
1333__END_DECLS
1334
1335#endif /* __DC_PVR_H */
int mode
Definition 2ndmix.c:539
pvr_init_params_t params
Definition 2ndmix.c:820
static struct @89 data[BARRIER_COUNT]
static pvr_ptr_t txr
Definition bump.c:28
Various common macros used throughout the codebase.
Constants for areas of the system memory map.
#define PVR_BINSIZE_16
16-word (64-byte) length
Definition pvr.h:650
#define PVR_BINSIZE_0
0-length (disables the list)
Definition pvr.h:648
void pvr_poly_cxt_txr(pvr_poly_cxt_t *dst, pvr_list_t list, int textureformat, int tw, int th, pvr_ptr_t textureaddr, pvr_filter_mode_t filtering)
Fill in a polygon context for a textured polygon.
void pvr_poly_cxt_col_mod(pvr_poly_cxt_t *dst, pvr_list_t list)
Fill in a polygon context for non-textured polygons affected by a modifier volume.
void pvr_sprite_cxt_txr(pvr_sprite_cxt_t *dst, pvr_list_t list, int textureformat, int tw, int th, pvr_ptr_t textureaddr, pvr_filter_mode_t filtering)
Fill in a sprite context for a textured sprite.
void pvr_poly_cxt_txr_mod(pvr_poly_cxt_t *dst, pvr_list_t list, int textureformat, int tw, int th, pvr_ptr_t textureaddr, pvr_filter_mode_t filtering, int textureformat2, int tw2, int th2, pvr_ptr_t textureaddr2, pvr_filter_mode_t filtering2)
Fill in a polygon context for a textured polygon affected by modifier volumes.
void pvr_poly_cxt_col(pvr_poly_cxt_t *dst, pvr_list_t list)
Fill in a polygon context for non-textured polygons.
void pvr_sprite_cxt_col(pvr_sprite_cxt_t *dst, pvr_list_t list)
Fill in a sprite context for non-textured sprites.
void pvr_send_to_ta(void *data)
Upload a 32-byte payload to the Tile Accelerator.
int pvr_shutdown(void)
Shut down the PVR chip from ready status.
int pvr_init_defaults(void)
Simple PVR initialization.
int pvr_init(const pvr_init_params_t *params)
Initialize the PVR chip to ready status.
static const pvr_init_params_t pvr_default_params
PVR initialization structure defaults.
Definition pvr.h:727
void * pvr_set_vertbuf(pvr_list_t list, void *buffer, size_t len)
Setup a vertex buffer for one of the list types.
int pvr_list_flush(pvr_list_t list)
Flush the buffered data of the given list type to the TA.
int pvr_prim(const void *data, size_t size)
Submit a primitive of the current list type.
int pvr_list_finish(void)
End collecting data for the current list type.
int pvr_list_prim(pvr_list_t list, const void *data, size_t size)
Submit a primitive of the given list type.
int pvr_list_begin(pvr_list_t list)
Begin collecting data for the given list type.
pvr_mip_bias_t
Definition pvr.h:90
@ PVR_MIPBIAS_1_50
Definition pvr.h:96
@ PVR_MIPBIAS_3_25
Definition pvr.h:103
@ PVR_MIPBIAS_3_50
Definition pvr.h:104
@ PVR_MIPBIAS_2_00
Definition pvr.h:98
@ PVR_MIPBIAS_0_75
Definition pvr.h:93
@ PVR_MIPBIAS_1_00
Definition pvr.h:94
@ PVR_MIPBIAS_0_50
Definition pvr.h:92
@ PVR_MIPBIAS_2_50
Definition pvr.h:100
@ PVR_MIPBIAS_0_25
Definition pvr.h:91
@ PVR_MIPBIAS_3_75
Definition pvr.h:105
@ PVR_MIPBIAS_2_25
Definition pvr.h:99
@ PVR_MIPBIAS_1_25
Definition pvr.h:95
@ PVR_MIPBIAS_NORMAL
Definition pvr.h:106
@ PVR_MIPBIAS_2_75
Definition pvr.h:101
@ PVR_MIPBIAS_1_75
Definition pvr.h:97
@ PVR_MIPBIAS_3_00
Definition pvr.h:102
void pvr_mod_compile(pvr_mod_hdr_t *dst, pvr_list_t list, uint32_t mode, uint32_t cull)
Create a modifier volume header.
void pvr_poly_compile(pvr_poly_hdr_t *dst, const pvr_poly_cxt_t *src)
Compile a polygon context into a polygon header.
void pvr_poly_mod_compile(pvr_poly_mod_hdr_t *dst, const pvr_poly_cxt_t *src)
Compile a polygon context into a polygon header that is affected by modifier volumes.
void pvr_sprite_compile(pvr_sprite_hdr_t *dst, const pvr_sprite_cxt_t *src)
Compile a sprite context into a sprite header.
pvr_txr_shading_mode_t
Texture color calculation modes.
Definition pvr_header.h:124
pvr_poly_hdr_t pvr_poly_mod_hdr_t
Definition pvr.h:383
pvr_poly_hdr_t pvr_poly_ic_hdr_t
Definition pvr.h:373
pvr_poly_hdr_t pvr_sprite_hdr_t
Definition pvr.h:393
pvr_filter_mode_t
Texture sampling modes.
Definition pvr_header.h:132
pvr_cull_mode_t
Primitive culling modes.
Definition pvr_header.h:77
pvr_fog_type_t
Fog modes.
Definition pvr_header.h:145
pvr_depthcmp_mode_t
Depth comparison modes.
Definition pvr_header.h:88
pvr_color_fmts_t
Vertex color formats.
Definition pvr_header.h:38
pvr_strip_len_t
Triangle strip length.
Definition pvr_header.h:190
pvr_poly_hdr_t pvr_mod_hdr_t
Definition pvr.h:403
pvr_blend_mode_t
Blending modes.
Definition pvr_header.h:157
pvr_clip_mode_t
Primitive clipping modes.
Definition pvr_header.h:49
pvr_list_t
PVR rendering lists.
Definition pvr_header.h:60
int pvr_scene_finish(void)
Call this after you have finished submitting all data for a frame.
void pvr_scene_begin_txr(pvr_ptr_t txr, uint32_t *rx, uint32_t *ry)
Begin collecting data for a frame of 3D output to the specified texture.
void pvr_scene_begin(void)
Begin collecting data for a frame of 3D output to the off-screen frame buffer.
int pvr_check_ready(void)
Check if the PVR system is ready for another frame to be submitted.
int pvr_wait_ready(void)
Block the caller until the PVR system is ready for another frame to be submitted.
int pvr_scene_begin_rtt(pvr_ptr_t txr, uint32_t render_w, uint32_t render_h, uint32_t stride_px)
Begin collecting scene data for rendering into a texture target with an explicit render size.
int pvr_wait_render_done(void)
Block the caller until the PVR has finished rendering the previous frame.
#define PVR_TXRFMT_POW2_STRIDE
Stride is a power-of-two.
Definition pvr.h:317
static const uint32_t PVR_TXRFMT_NOSTRIDE
Definition pvr.h:321
static const uint32_t PVR_TXRFMT_STRIDE
Definition pvr.h:322
#define PVR_TXRFMT_X32_STRIDE
Stride is multiple of 32.
Definition pvr.h:318
pvr_ptr_t pvr_get_back_buffer(void)
Get a pointer to the back buffer.
pvr_ptr_t pvr_get_front_buffer(void)
Get a pointer to the front buffer.
pvr_uv_clamp_t
Definition pvr.h:145
@ PVR_UVCLAMP_UV
Clamp U and V.
Definition pvr.h:149
@ PVR_UVCLAMP_NONE
Disable clamping.
Definition pvr.h:146
@ PVR_UVCLAMP_U
Clamp U only.
Definition pvr.h:148
@ PVR_UVCLAMP_V
Clamp V only.
Definition pvr.h:147
pvr_uv_flip_t
Definition pvr.h:127
@ PVR_UVFLIP_NONE
No flipped coordinates.
Definition pvr.h:128
@ PVR_UVFLIP_UV
Flip U and V.
Definition pvr.h:131
@ PVR_UVFLIP_V
Flip V only.
Definition pvr.h:129
@ PVR_UVFLIP_U
Flip U only.
Definition pvr.h:130
void pvr_vertbuf_written(pvr_list_t list, size_t amt)
Notify the PVR system that data have been written into the output buffer for the given list.
int pvr_vertex_dma_enabled(void)
Is vertex DMA enabled?
void * pvr_vertbuf_tail(pvr_list_t list)
Retrieve a pointer to the current output location in the DMA buffer for the requested list.
void * pvr_ptr_t
PVR texture memory pointer.
Definition pvr_mem.h:45
Platform-independent image type.
static char buffer[256]
Definition porthelper.c:11
Second PowerVR (CLXB) on NAOMI 2.
API for utilizing the DMA with the PVR for rendering.
Public API for the PVR's hardware fog.
Polygon/Sprite header definitions.
All deprecated PVR API Constants.
VRAM Management and Access.
Miscellaneous utilities for the PVR API.
Palette API for the PowerVR.
PVR Driver Registers.
Texture management with the PVR 3D API.
Macros to help dealing with register fields.
static pvr_list_t list
Definition shadow.c:25
Functions to access the SH4 Store Queues.
PVR initialization structure.
Definition pvr.h:666
int fsaa_enabled
Enable horizontal scaling?
Definition pvr.h:690
int vbuf_doublebuf_disabled
Disable vertex buffer double-buffering.
Definition pvr.h:716
int dma_enabled
Enable vertex DMA?
Definition pvr.h:683
int vertex_buf_size
Vertex buffer size (should be a nice round number)
Definition pvr.h:675
int autosort_disabled
Disable translucent polygon autosort?
Definition pvr.h:698
int opb_overflow_count
OPB Overflow Count.
Definition pvr.h:709
PVR vertex type: Modifier volume.
Definition pvr.h:551
uint32_t d1
Dummy value.
Definition pvr.h:563
uint32_t d4
Dummy value.
Definition pvr.h:566
float by
Second Y coordinate.
Definition pvr.h:558
float ay
First Y coordinate.
Definition pvr.h:555
float ax
First X coordinate.
Definition pvr.h:554
uint32_t d3
Dummy value.
Definition pvr.h:565
float cz
Third Z coordinate.
Definition pvr.h:562
float bz
Second Z coordinate.
Definition pvr.h:559
float cy
Third Y coordinate.
Definition pvr.h:561
uint32_t d6
Dummy value.
Definition pvr.h:568
uint32_t d2
Dummy value.
Definition pvr.h:564
uint32_t d5
Dummy value.
Definition pvr.h:567
float bx
Second X coordinate.
Definition pvr.h:557
float az
First Z coordinate.
Definition pvr.h:556
float cx
Third X coordinate.
Definition pvr.h:560
PVR polygon context.
Definition pvr.h:170
pvr_list_t list_type
Primitive list.
Definition pvr.h:171
bool specular
Enable offset color outside modifier.
Definition pvr.h:180
pvr_blend_mode_t src
Source blending mode outside modifier.
Definition pvr.h:188
pvr_uv_clamp_t uv_clamp
Enable/disable U/V clamping.
Definition pvr.h:212
pvr_cull_mode_t culling
Culling mode.
Definition pvr.h:176
bool mipmap
Enable/disable mipmaps.
Definition pvr.h:209
pvr_fog_type_t fog_type2
Fog type inside modifier.
Definition pvr.h:182
bool modifier_mode
True normal; false: cheap shadow.
Definition pvr.h:179
bool alpha2
Enable alpha inside modifier.
Definition pvr.h:181
pvr_uv_flip_t uv_flip
Enable/disable U/V flipping.
Definition pvr.h:211
bool color_clamp
Enable color clamping outside modifer.
Definition pvr.h:177
pvr_strip_len_t strip_len
Max triangles per strip piece stored by the TA (defaults to PVR_STRIP_LEN_2)
Definition pvr.h:184
pvr_filter_mode_t filter
Filtering mode.
Definition pvr.h:208
bool write
Enable depth writes.
Definition pvr.h:204
pvr_ptr_t base
Texture pointer.
Definition pvr.h:219
pvr_blend_mode_t src2
Source blending mode inside modifier.
Definition pvr.h:192
struct pvr_poly_cxt_t::@51 txr2
Texturing params inside modifier.
bool enable
Enable/disable texturing.
Definition pvr.h:207
bool shading
Enable gourad shading.
Definition pvr.h:174
pvr_mip_bias_t mipmap_bias
Mipmap bias.
Definition pvr.h:210
int width
Texture width (requires a power of 2)
Definition pvr.h:215
pvr_blend_mode_t dst
Dest blending mode outside modifier.
Definition pvr.h:189
bool color_clamp2
Enable color clamping inside modifer.
Definition pvr.h:183
int height
Texture height (requires a power of 2)
Definition pvr.h:216
bool uv
True: 16-bit floating-point U/Vs; False: 32-bit.
Definition pvr.h:199
pvr_depthcmp_mode_t comparison
Depth comparison mode.
Definition pvr.h:203
bool src_enable2
Source blending mode inside modifier.
Definition pvr.h:194
pvr_blend_mode_t dst2
Dest blending mode inside modifier.
Definition pvr.h:193
bool modifier
Enable modifier effects.
Definition pvr.h:200
bool src_enable
Source blending enable outside modifier.
Definition pvr.h:190
pvr_color_fmts_t color
Color format in vertex.
Definition pvr.h:198
pvr_txr_shading_mode_t env
Texture color contribution.
Definition pvr.h:214
pvr_fog_type_t fog_type
Fog type outside modifier.
Definition pvr.h:175
bool alpha
Enable alpha outside modifier.
Definition pvr.h:173
pvr_clip_mode_t clip_mode
Clipping mode.
Definition pvr.h:178
bool dst_enable2
Dest blending mode inside modifier.
Definition pvr.h:195
bool dst_enable
Dest blending enable outside modifier.
Definition pvr.h:191
int format
Texture format.
Definition pvr.h:217
PVR polygon header.
Definition pvr_header.h:319
PVR vertex type: Untextured sprite.
Definition pvr.h:526
float bz
Second Z coordinate.
Definition pvr.h:534
float ay
First Y coordinate.
Definition pvr.h:530
uint32_t d3
Dummy value.
Definition pvr.h:542
float cz
Third Z coordinate.
Definition pvr.h:537
float bx
Second X coordinate.
Definition pvr.h:532
uint32_t d1
Dummy value.
Definition pvr.h:540
float cy
Third Y coordinate.
Definition pvr.h:536
float ax
First X coordinate.
Definition pvr.h:529
float by
Second Y coordinate.
Definition pvr.h:533
uint32_t d4
Dummy value.
Definition pvr.h:543
float dy
Fourth Y coordinate.
Definition pvr.h:539
uint32_t d2
Dummy value.
Definition pvr.h:541
float cx
Third X coordinate.
Definition pvr.h:535
float az
First Z coordinate.
Definition pvr.h:531
float dx
Fourth X coordinate.
Definition pvr.h:538
PVR sprite context.
Definition pvr.h:237
bool alpha
Enable alpha.
Definition pvr.h:240
bool mipmap
Enable/disable mipmaps.
Definition pvr.h:260
bool enable
Enable/disable texturing.
Definition pvr.h:258
pvr_mip_bias_t mipmap_bias
Mipmap bias.
Definition pvr.h:261
bool src_enable
Source blending enable.
Definition pvr.h:250
pvr_uv_clamp_t uv_clamp
Enable/disable U/V clamping.
Definition pvr.h:263
pvr_blend_mode_t dst
Dest blending mode.
Definition pvr.h:249
pvr_fog_type_t fog_type
Fog type.
Definition pvr.h:241
bool write
Enable depth writes.
Definition pvr.h:255
pvr_uv_flip_t uv_flip
Enable/disable U/V flipping.
Definition pvr.h:262
bool specular
Enable offset color.
Definition pvr.h:245
bool color_clamp
Enable color clamp.
Definition pvr.h:243
pvr_list_t list_type
Primitive list.
Definition pvr.h:238
pvr_clip_mode_t clip_mode
Clipping mode.
Definition pvr.h:244
int width
Texture width (requires a power of 2)
Definition pvr.h:266
pvr_txr_shading_mode_t env
Texture color contribution.
Definition pvr.h:265
pvr_ptr_t base
Texture pointer.
Definition pvr.h:270
pvr_blend_mode_t src
Source blending mode.
Definition pvr.h:248
pvr_filter_mode_t filter
Filtering mode.
Definition pvr.h:259
pvr_cull_mode_t culling
Culling mode.
Definition pvr.h:242
pvr_depthcmp_mode_t comparison
Depth comparison mode.
Definition pvr.h:254
int height
Texture height (requires a power of 2)
Definition pvr.h:267
bool dst_enable
Dest blending enable.
Definition pvr.h:251
int format
Texture format.
Definition pvr.h:268
PVR vertex type: Textured sprite.
Definition pvr.h:501
float bz
Second Z coordinate.
Definition pvr.h:509
float dx
Fourth X coordinate.
Definition pvr.h:513
float az
First Z coordinate.
Definition pvr.h:506
float ax
First X coordinate.
Definition pvr.h:504
uint32_t buv
Second U/V texture coordinates.
Definition pvr.h:517
float cz
Third Z coordinate.
Definition pvr.h:512
uint32_t dummy
Dummy value.
Definition pvr.h:515
float by
Second Y coordinate.
Definition pvr.h:508
uint32_t auv
First U/V texture coordinates.
Definition pvr.h:516
float dy
Fourth Y coordinate.
Definition pvr.h:514
float cx
Third X coordinate.
Definition pvr.h:510
uint32_t cuv
Third U/V texture coordinates.
Definition pvr.h:518
float bx
Second X coordinate.
Definition pvr.h:507
float cy
Third Y coordinate.
Definition pvr.h:511
float ay
First Y coordinate.
Definition pvr.h:505
PVR vertex type: Non-textured, packed color, affected by modifier volume.
Definition pvr.h:449
float z
Z coordinate.
Definition pvr.h:454
uint32_t d1
Dummy value.
Definition pvr.h:457
uint32_t argb0
Vertex color (outside volume)
Definition pvr.h:455
float x
X coordinate.
Definition pvr.h:452
float y
Y coordinate.
Definition pvr.h:453
uint32_t d2
Dummy value.
Definition pvr.h:458
uint32_t argb1
Vertex color (inside volume)
Definition pvr.h:456
Generic PVR vertex type.
Definition pvr.h:421
float z
Z coordinate.
Definition pvr.h:426
float y
Y coordinate.
Definition pvr.h:425
float u
Texture U coordinate.
Definition pvr.h:429
uint32_t oargb
Vertex offset color.
Definition pvr.h:438
uint32_t argb1
Vertex color when modified, inside area.
Definition pvr.h:434
float x
X coordinate.
Definition pvr.h:424
float v
Texture V coordinate.
Definition pvr.h:430
uint32_t argb
Vertex color.
Definition pvr.h:437
uint32_t argb0
Vertex color when modified, outside area.
Definition pvr.h:433
PVR vertex type: Textured, packed color, affected by modifier volume.
Definition pvr.h:469
float z
Z coordinate.
Definition pvr.h:474
uint32_t oargb1
Vertex offset color (inside)
Definition pvr.h:482
uint32_t oargb0
Vertex offset color (outside)
Definition pvr.h:478
float x
X coordinate.
Definition pvr.h:472
float u0
Texture U coordinate (outside)
Definition pvr.h:475
uint32_t d2
Dummy value.
Definition pvr.h:484
float v0
Texture V coordinate (outside)
Definition pvr.h:476
uint32_t d4
Dummy value.
Definition pvr.h:486
float u1
Texture U coordinate (inside)
Definition pvr.h:479
float y
Y coordinate.
Definition pvr.h:473
float v1
Texture V coordinate (inside)
Definition pvr.h:480
uint32_t argb0
Vertex color (outside)
Definition pvr.h:477
uint32_t argb1
Vertex color (inside)
Definition pvr.h:481
uint32_t d1
Dummy value.
Definition pvr.h:483
uint32_t d3
Dummy value.
Definition pvr.h:485