KallistiOS  2.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
pvr.h
Go to the documentation of this file.
1 /* KallistiOS 2.0.0
2 
3  dc/pvr.h
4  Copyright (C) 2002 Dan Potter
5 
6  Low-level PVR 3D interface for the DC
7  Note: this API does _not_ handle any sort of transformations
8  (including perspective!) so for that, you should look to KGL.
9 */
10 
11 /** \file dc/pvr.h
12  \brief Low-level PVR (3D hardware) interface.
13 
14  This file provides support for using the PVR 3D hardware in the Dreamcast.
15  Note that this does not handle any sort of perspective transformations or
16  anything of the like. This is just a very thin wrapper around the actual
17  hardware support.
18 
19  This file is used for pretty much everything related to the PVR, from memory
20  management to actual primitive rendering.
21 
22  \author Dan Potter
23  \author Roger Cattermole
24  \author Paul Boese
25  \author Brian Paul
26  \author Lawrence Sebald
27  \author Benoit Miller
28 */
29 
30 #ifndef __DC_PVR_H
31 #define __DC_PVR_H
32 
33 #include <sys/cdefs.h>
34 __BEGIN_DECLS
35 
36 #include <arch/types.h>
37 #include <dc/sq.h>
38 #include <kos/img.h>
39 
40 /* Data types ********************************************************/
41 
42 /** \brief PVR texture memory pointer.
43 
44  Unlike the old "TA" system, PVR pointers in the new system are actually SH-4
45  compatible pointers and can be used directly in place of ta_txr_map().
46 
47  Not that anyone probably even remembers the old TA system anymore... */
48 typedef void * pvr_ptr_t;
49 
50 /** \brief PVR list specification.
51 
52  Each primitive in the PVR is submitted to one of the hardware primitive
53  lists. This type is an identifier for a list.
54 
55  \see pvr_lists
56 */
58 
59 /** \brief PVR polygon context.
60 
61  You should use this more human readable format for specifying your polygon
62  contexts, and then compile them into polygon headers when you are ready to
63  start using them.
64 
65  This has embedded structures in it for two reasons; the first reason is to
66  make it easier for me to add new stuff later without breaking existing code.
67  The second reason is to make it more readable and usable.
68 
69  Unfortunately, it seems that Doxygen chokes up a little bit on this
70  structure, and others like it. The documentation should still be mostly
71  understandable though...
72 
73  \headerfile dc/pvr.h
74 */
75 typedef struct {
76  int list_type; /**< \brief Primitive list
77  \see pvr_lists */
78  struct {
79  int alpha; /**< \brief Enable or disable alpha outside modifier
80  \see pvr_alpha_switch */
81  int shading; /**< \brief Shading type
82  \see pvr_shading_types */
83  int fog_type; /**< \brief Fog type outside modifier
84  \see pvr_fog_types */
85  int culling; /**< \brief Culling mode
86  \see pvr_cull_modes */
87  int color_clamp; /**< \brief Color clamp enable/disable outside modifier
88  \see pvr_colclamp_switch */
89  int clip_mode; /**< \brief Clipping mode
90  \see pvr_clip_modes */
91  int modifier_mode; /**< \brief Modifier mode */
92  int alpha2; /**< \brief Enable/disable alpha inside modifier
93  \see pvr_alpha_switch */
94  int fog_type2; /**< \brief Fog type inside modifier
95  \see pvr_fog_types */
96  int color_clamp2; /**< \brief Color clamp enable/disable inside modifier
97  \see pvr_colclamp_switch */
98  } gen; /**< \brief General parameters */
99  struct {
100  int src; /**< \brief Source blending mode outside modifier
101  \see pvr_blend_modes */
102  int dst; /**< \brief Dest blending mode outside modifier
103  \see pvr_blend_modes */
104  int src_enable; /**< \brief Source blending enable outside modifier
105  \see pvr_blend_switch */
106  int dst_enable; /**< \brief Dest blending enable outside modifier
107  \see pvr_blend_switch */
108  int src2; /**< \brief Source blending mode inside modifier
109  \see pvr_blend_modes */
110  int dst2; /**< \brief Dest blending mode inside modifier
111  \see pvr_blend_modes */
112  int src_enable2; /**< \brief Source blending mode inside modifier
113  \see pvr_blend_switch */
114  int dst_enable2; /**< \brief Dest blending mode inside modifier
115  \see pvr_blend_switch */
116  } blend; /**< \brief Blending parameters */
117  struct {
118  int color; /**< \brief Color format in vertex
119  \see pvr_color_fmts */
120  int uv; /**< \brief U/V data format in vertex
121  \see pvr_uv_fmts */
122  int modifier; /**< \brief Enable or disable modifier effect
123  \see pvr_mod_switch */
124  } fmt; /**< \brief Format control */
125  struct {
126  int comparison; /**< \brief Depth comparison mode
127  \see pvr_depth_modes */
128  int write; /**< \brief Enable or disable depth writes
129  \see pvr_depth_switch */
130  } depth; /**< \brief Depth comparison/write modes */
131  struct {
132  int enable; /**< \brief Enable/disable texturing
133  \see pvr_txr_switch */
134  int filter; /**< \brief Filtering mode
135  \see pvr_filter_modes */
136  int mipmap; /**< \brief Enable/disable mipmaps
137  \see pvr_mip_switch */
138  int mipmap_bias; /**< \brief Mipmap bias
139  \see pvr_mip_bias */
140  int uv_flip; /**< \brief Enable/disable U/V flipping
141  \see pvr_uv_flip */
142  int uv_clamp; /**< \brief Enable/disable U/V clamping
143  \see pvr_uv_clamp */
144  int alpha; /**< \brief Enable/disable texture alpha
145  \see pvr_txralpha_switch */
146  int env; /**< \brief Texture color contribution
147  \see pvr_txrenv_modes */
148  int width; /**< \brief Texture width (requires a power of 2) */
149  int height; /**< \brief Texture height (requires a power of 2) */
150  int format; /**< \brief Texture format
151  \see pvr_txr_fmts */
152  pvr_ptr_t base; /**< \brief Texture pointer */
153  } txr; /**< \brief Texturing params outside modifier */
154  struct {
155  int enable; /**< \brief Enable/disable texturing
156  \see pvr_txr_switch */
157  int filter; /**< \brief Filtering mode
158  \see pvr_filter_modes */
159  int mipmap; /**< \brief Enable/disable mipmaps
160  \see pvr_mip_switch */
161  int mipmap_bias; /**< \brief Mipmap bias
162  \see pvr_mip_bias */
163  int uv_flip; /**< \brief Enable/disable U/V flipping
164  \see pvr_uv_flip */
165  int uv_clamp; /**< \brief Enable/disable U/V clamping
166  \see pvr_uv_clamp */
167  int alpha; /**< \brief Enable/disable texture alpha
168  \see pvr_txralpha_switch */
169  int env; /**< \brief Texture color contribution
170  \see pvr_txrenv_modes */
171  int width; /**< \brief Texture width (requires a power of 2) */
172  int height; /**< \brief Texture height (requires a power of 2) */
173  int format; /**< \brief Texture format
174  \see pvr_txr_fmts */
175  pvr_ptr_t base; /**< \brief Texture pointer */
176  } txr2; /**< \brief Texturing params inside modifier */
178 
179 /** \brief PVR sprite context.
180 
181  You should use this more human readable format for specifying your sprite
182  contexts, and then compile them into sprite headers when you are ready to
183  start using them.
184 
185  Unfortunately, it seems that Doxygen chokes up a little bit on this
186  structure, and others like it. The documentation should still be mostly
187  understandable though...
188 
189  \headerfile dc/pvr.h
190 */
191 typedef struct {
192  int list_type; /**< \brief Primitive list
193  \see pvr_lists */
194  struct {
195  int alpha; /**< \brief Enable or disable alpha outside modifier
196  \see pvr_alpha_switch */
197  int fog_type; /**< \brief Fog type outside modifier
198  \see pvr_fog_types */
199  int culling; /**< \brief Culling mode
200  \see pvr_cull_modes */
201  int color_clamp; /**< \brief Color clamp enable/disable outside modifier
202  \see pvr_colclamp_switch */
203  int clip_mode; /**< \brief Clipping mode
204  \see pvr_clip_modes */
205  } gen; /**< \brief General parameters */
206  struct {
207  int src; /**< \brief Source blending mode outside modifier
208  \see pvr_blend_modes */
209  int dst; /**< \brief Dest blending mode outside modifier
210  \see pvr_blend_modes */
211  int src_enable; /**< \brief Source blending enable outside modifier
212  \see pvr_blend_switch */
213  int dst_enable; /**< \brief Dest blending enable outside modifier
214  \see pvr_blend_switch */
215  } blend;
216  struct {
217  int comparison; /**< \brief Depth comparison mode
218  \see pvr_depth_modes */
219  int write; /**< \brief Enable or disable depth writes
220  \see pvr_depth_switch */
221  } depth; /**< \brief Depth comparison/write modes */
222  struct {
223  int enable; /**< \brief Enable/disable texturing
224  \see pvr_txr_switch */
225  int filter; /**< \brief Filtering mode
226  \see pvr_filter_modes */
227  int mipmap; /**< \brief Enable/disable mipmaps
228  \see pvr_mip_switch */
229  int mipmap_bias; /**< \brief Mipmap bias
230  \see pvr_mip_bias */
231  int uv_flip; /**< \brief Enable/disable U/V flipping
232  \see pvr_uv_flip */
233  int uv_clamp; /**< \brief Enable/disable U/V clamping
234  \see pvr_uv_clamp */
235  int alpha; /**< \brief Enable/disable texture alpha
236  \see pvr_txralpha_switch */
237  int env; /**< \brief Texture color contribution
238  \see pvr_txrenv_modes */
239  int width; /**< \brief Texture width (requires a power of 2) */
240  int height; /**< \brief Texture height (requires a power of 2) */
241  int format; /**< \brief Texture format
242  \see pvr_txr_fmts */
243  pvr_ptr_t base; /**< \brief Texture pointer */
244  } txr; /**< \brief Texturing params */
246 
247 /* Constants for the above structure; thanks to Benoit Miller for these */
248 
249 /** \defgroup pvr_lists PVR primitive list types
250 
251  Each primitive submitted to the PVR must be placed in one of these lists,
252  depending on its characteristics.
253 
254  @{
255 */
256 #define PVR_LIST_OP_POLY 0 /**< \brief Opaque polygon list */
257 #define PVR_LIST_OP_MOD 1 /**< \brief Opaque modifier list */
258 #define PVR_LIST_TR_POLY 2 /**< \brief Translucent polygon list */
259 #define PVR_LIST_TR_MOD 3 /**< \brief Translucent modifier list*/
260 #define PVR_LIST_PT_POLY 4 /**< \brief Punch-thru polygon list */
261 /** @} */
262 
263 /** \defgroup pvr_shading_types PVR shading modes
264 
265  Each polygon can define how it wants to be shaded, be it with flat or
266  Gouraud shading using these constants in the appropriate place in its
267  pvr_poly_cxt_t.
268 
269  @{
270 */
271 #define PVR_SHADE_FLAT 0 /**< \brief Use flat shading */
272 #define PVR_SHADE_GOURAUD 1 /**< \brief Use Gouraud shading */
273 /** @} */
274 
275 /** \defgroup pvr_depth_modes PVR depth comparison modes
276 
277  These set the depth function used for comparisons.
278 
279  @{
280 */
281 #define PVR_DEPTHCMP_NEVER 0 /**< \brief Never pass */
282 #define PVR_DEPTHCMP_LESS 1 /**< \brief Less than */
283 #define PVR_DEPTHCMP_EQUAL 2 /**< \brief Equal to */
284 #define PVR_DEPTHCMP_LEQUAL 3 /**< \brief Less than or equal to */
285 #define PVR_DEPTHCMP_GREATER 4 /**< \brief Greater than */
286 #define PVR_DEPTHCMP_NOTEQUAL 5 /**< \brief Not equal to */
287 #define PVR_DEPTHCMP_GEQUAL 6 /**< \brief Greater than or equal to */
288 #define PVR_DEPTHCMP_ALWAYS 7 /**< \brief Always pass */
289 /** @} */
290 
291 /** \defgroup pvr_cull_modes PVR culling modes
292 
293  These culling modes can be set by polygons to determine when they are
294  culled. They work pretty much as you'd expect them to if you've ever used
295  any 3D hardware before.
296 
297  @{
298 */
299 #define PVR_CULLING_NONE 0 /**< \brief Disable culling */
300 #define PVR_CULLING_SMALL 1 /**< \brief Cull if small */
301 #define PVR_CULLING_CCW 2 /**< \brief Cull if counterclockwise */
302 #define PVR_CULLING_CW 3 /**< \brief Cull if clockwise */
303 /** @} */
304 
305 /** \defgroup pvr_depth_switch Enable or disable PVR depth writes
306  @{
307 */
308 #define PVR_DEPTHWRITE_ENABLE 0 /**< \brief Update the Z value */
309 #define PVR_DEPTHWRITE_DISABLE 1 /**< \brief Do not update the Z value */
310 /** @} */
311 
312 /** \defgroup pvr_txr_switch Enable or disable texturing on polygons
313  @{
314 */
315 #define PVR_TEXTURE_DISABLE 0 /**< \brief Disable texturing */
316 #define PVR_TEXTURE_ENABLE 1 /**< \brief Enable texturing */
317 /** @} */
318 
319 /** \defgroup pvr_blend_modes PVR blending modes
320 
321  These are all the blending modes that can be done with regard to alpha
322  blending on the PVR.
323 
324  @{
325 */
326 #define PVR_BLEND_ZERO 0 /**< \brief None of this color */
327 #define PVR_BLEND_ONE 1 /**< \brief All of this color */
328 #define PVR_BLEND_DESTCOLOR 2 /**< \brief Destination color */
329 #define PVR_BLEND_INVDESTCOLOR 3 /**< \brief Inverse of destination color */
330 #define PVR_BLEND_SRCALPHA 4 /**< \brief Blend with source alpha */
331 #define PVR_BLEND_INVSRCALPHA 5 /**< \brief Blend with inverse source alpha */
332 #define PVR_BLEND_DESTALPHA 6 /**< \brief Blend with destination alpha */
333 #define PVR_BLEND_INVDESTALPHA 7 /**< \brief Blend with inverse destination alpha */
334 /** @} */
335 
336 /** \defgroup pvr_blend_switch Enable or disable blending
337  @{
338 */
339 #define PVR_BLEND_DISABLE 0 /**< \brief Disable blending */
340 #define PVR_BLEND_ENABLE 1 /**< \brief Enable blending */
341 /** @} */
342 
343 /** \defgroup pvr_fog_types PVR fog modes
344 
345  Each polygon can decide what fog type is used with regard to it using these
346  constants in its pvr_poly_cxt_t.
347 
348  @{
349 */
350 #define PVR_FOG_TABLE 0 /**< \brief Table fog */
351 #define PVR_FOG_VERTEX 1 /**< \brief Vertex fog */
352 #define PVR_FOG_DISABLE 2 /**< \brief Disable fog */
353 #define PVR_FOG_TABLE2 3 /**< \brief Table fog mode 2 */
354 /** @} */
355 
356 /** \defgroup pvr_clip_modes PVR clipping modes
357 
358  These control how primitives are clipped against the user clipping area.
359 
360  @{
361 */
362 #define PVR_USERCLIP_DISABLE 0 /**< \brief Disable clipping */
363 #define PVR_USERCLIP_INSIDE 2 /**< \brief Enable clipping inside area */
364 #define PVR_USERCLIP_OUTSIDE 3 /**< \brief Enable clipping outside area */
365 /** @} */
366 
367 /** \defgroup pvr_colclamp_switch Enable or disable color clamping
368 
369  Enabling color clamping will clamp colors between the minimum and maximum
370  values before any sort of fog processing.
371 
372  @{
373 */
374 #define PVR_CLRCLAMP_DISABLE 0 /**< \brief Disable color clamping */
375 #define PVR_CLRCLAMP_ENABLE 1 /**< \brief Enable color clamping */
376 /** @} */
377 
378 /** \defgroup pvr_alpha_switch Enable or disable alpha blending
379 
380  This causes the alpha value in the vertex color to be paid attention to. It
381  really only makes sense to enable this for translucent or punch-thru polys.
382 
383  @{
384 */
385 #define PVR_ALPHA_DISABLE 0 /**< \brief Disable alpha blending */
386 #define PVR_ALPHA_ENABLE 1 /**< \brief Enable alpha blending */
387 /** @} */
388 
389 /** \defgroup pvr_txralpha_switch Enable or disable texture alpha blending
390 
391  This causes the alpha value in the texel color to be paid attention to. It
392  really only makes sense to enable this for translucent or punch-thru polys.
393 
394  @{
395 */
396 #define PVR_TXRALPHA_ENABLE 0 /**< \brief Enable alpha blending */
397 #define PVR_TXRALPHA_DISABLE 1 /**< \brief Disable alpha blending */
398 /** @} */
399 
400 /** \defgroup pvr_uv_flip Enable or disable U/V flipping on the PVR
401  @{
402 */
403 #define PVR_UVFLIP_NONE 0 /**< \brief No flipped coordinates */
404 #define PVR_UVFLIP_V 1 /**< \brief Flip V only */
405 #define PVR_UVFLIP_U 2 /**< \brief Flip U only */
406 #define PVR_UVFLIP_UV 3 /**< \brief Flip U and V */
407 /** @} */
408 
409 /** \defgroup pvr_uv_clamp Enable or disable clamping of U/V on the PVR
410  @{
411 */
412 #define PVR_UVCLAMP_NONE 0 /**< \brief Disable clamping */
413 #define PVR_UVCLAMP_V 1 /**< \brief Clamp V only */
414 #define PVR_UVCLAMP_U 2 /**< \brief Clamp U only */
415 #define PVR_UVCLAMP_UV 3 /**< \brief Clamp U and V */
416 /** @} */
417 
418 /** \defgroup pvr_filter_modes PVR texture sampling modes
419  @{
420 */
421 #define PVR_FILTER_NONE 0 /**< \brief No filtering (point sample) */
422 #define PVR_FILTER_NEAREST 0 /**< \brief No filtering (point sample) */
423 #define PVR_FILTER_BILINEAR 2 /**< \brief Bilinear interpolation */
424 #define PVR_FILTER_TRILINEAR1 4 /**< \brief Trilinear interpolation pass 1 */
425 #define PVR_FILTER_TRILINEAR2 6 /**< \brief Trilinear interpolation pass 2 */
426 /** @} */
427 
428 /** \defgroup pvr_mip_bias PVR mipmap bias modes
429  @{
430 */
431 #define PVR_MIPBIAS_NORMAL PVR_MIPBIAS_1_00 /* txr_mipmap_bias */
432 #define PVR_MIPBIAS_0_25 1
433 #define PVR_MIPBIAS_0_50 2
434 #define PVR_MIPBIAS_0_75 3
435 #define PVR_MIPBIAS_1_00 4
436 #define PVR_MIPBIAS_1_25 5
437 #define PVR_MIPBIAS_1_50 6
438 #define PVR_MIPBIAS_1_75 7
439 #define PVR_MIPBIAS_2_00 8
440 #define PVR_MIPBIAS_2_25 9
441 #define PVR_MIPBIAS_2_50 10
442 #define PVR_MIPBIAS_2_75 11
443 #define PVR_MIPBIAS_3_00 12
444 #define PVR_MIPBIAS_3_25 13
445 #define PVR_MIPBIAS_3_50 14
446 #define PVR_MIPBIAS_3_75 15
447 /** @} */
448 
449 /** \defgroup pvr_txrenv_modes Texture color calculation modes
450  @{
451 */
452 #define PVR_TXRENV_REPLACE 0 /**< \brief C = Ct, A = At */
453 #define PVR_TXRENV_MODULATE 1 /**< \brief C = Cs * Ct, A = At */
454 #define PVR_TXRENV_DECAL 2 /**< \brief C = (Cs * At) + (Cs * (1-At)), A = As */
455 #define PVR_TXRENV_MODULATEALPHA 3 /**< \brief C = Cs * Ct, A = As * At */
456 /** @} */
457 
458 /** \defgroup pvr_mip_switch Enable or disable PVR mipmap processing
459  @{
460 */
461 #define PVR_MIPMAP_DISABLE 0 /**< \brief Disable mipmap processing */
462 #define PVR_MIPMAP_ENABLE 1 /**< \brief Enable mipmap processing */
463 /** @} */
464 
465 /** \defgroup pvr_txr_fmts PVR texture formats
466 
467  These are the texture formats that the PVR supports. Note that some of
468  these, you can OR together with other values.
469 
470  @{
471 */
472 #define PVR_TXRFMT_NONE 0 /**< \brief No texture */
473 #define PVR_TXRFMT_VQ_DISABLE (0 << 30) /**< \brief Not VQ encoded */
474 #define PVR_TXRFMT_VQ_ENABLE (1 << 30) /**< \brief VQ encoded */
475 #define PVR_TXRFMT_ARGB1555 (0 << 27) /**< \brief 16-bit ARGB1555 */
476 #define PVR_TXRFMT_RGB565 (1 << 27) /**< \brief 16-bit RGB565 */
477 #define PVR_TXRFMT_ARGB4444 (2 << 27) /**< \brief 16-bit ARGB4444 */
478 #define PVR_TXRFMT_YUV422 (3 << 27) /**< \brief YUV422 format */
479 #define PVR_TXRFMT_BUMP (4 << 27) /**< \brief Bumpmap format */
480 #define PVR_TXRFMT_PAL4BPP (5 << 27) /**< \brief 4BPP paletted format */
481 #define PVR_TXRFMT_PAL8BPP (6 << 27) /**< \brief 8BPP paletted format */
482 #define PVR_TXRFMT_TWIDDLED (0 << 26) /**< \brief Texture is twiddled */
483 #define PVR_TXRFMT_NONTWIDDLED (1 << 26) /**< \brief Texture is not twiddled */
484 #define PVR_TXRFMT_NOSTRIDE (0 << 21) /**< \brief Texture is not strided */
485 #define PVR_TXRFMT_STRIDE (1 << 21) /**< \brief Texture is strided */
486 
487 /* OR one of these into your texture format if you need it. Note that
488  these coincide with the twiddled/stride bits, so you can't have a
489  non-twiddled/strided texture that's paletted! */
490 /** \brief 8BPP palette selector
491  \param x The palette index */
492 #define PVR_TXRFMT_8BPP_PAL(x) ((x) << 25)
493 
494 /** \brief 4BPP palette selector
495  \param x The palette index */
496 #define PVR_TXRFMT_4BPP_PAL(x) ((x) << 21)
497 /** @} */
498 
499 /** \defgroup pvr_color_fmts PVR vertex color formats
500 
501  These control how colors are represented in polygon data.
502 
503  @{
504 */
505 #define PVR_CLRFMT_ARGBPACKED 0 /**< \brief 32-bit integer ARGB */
506 #define PVR_CLRFMT_4FLOATS 1 /**< \brief 4 floating point values */
507 #define PVR_CLRFMT_INTENSITY 2 /**< \brief Intensity color */
508 #define PVR_CLRFMT_INTENSITY_PREV 3 /**< \brief Use last intensity */
509 /** @} */
510 
511 /** \defgroup pvr_uv_fmts PVR U/V data format control
512  @{
513 */
514 #define PVR_UVFMT_32BIT 0 /**< \brief 32-bit floating point U/V */
515 #define PVR_UVFMT_16BIT 1 /**< \brief 16-bit floating point U/V */
516 /** @} */
517 
518 /** \defgroup pvr_mod_switch Enable or disable modifier effects
519  @{
520 */
521 #define PVR_MODIFIER_DISABLE 0 /**< \brief Disable modifier effects */
522 #define PVR_MODIFIER_ENABLE 1 /**< \brief Enable modifier effects */
523 /** @} */
524 
525 #define PVR_MODIFIER_CHEAP_SHADOW 0
526 #define PVR_MODIFIER_NORMAL 1
527 
528 /** \defgroup pvr_mod_modes Modifier volume mode parameters
529 
530  All triangles in a single modifier volume should be of the other poly type,
531  except for the last one. That should be either of the other two types,
532  depending on whether you want an inclusion or exclusion volume.
533 
534  @{
535 */
536 #define PVR_MODIFIER_OTHER_POLY 0 /**< \brief Not the last polygon in the volume */
537 #define PVR_MODIFIER_INCLUDE_LAST_POLY 1 /**< \brief Last polygon, inclusion volume */
538 #define PVR_MODIFIER_EXCLUDE_LAST_POLY 2 /**< \brief Last polygon, exclusion volume */
539 /** @} */
540 
541 
542 /** \brief PVR polygon header.
543 
544  This is the hardware equivalent of a rendering context; you'll create one of
545  these from your pvr_poly_cxt_t and use it for submission to the hardware.
546 
547  \headerfile dc/pvr.h
548 */
549 typedef struct {
550  uint32 cmd; /**< \brief TA command */
551  uint32 mode1; /**< \brief Parameter word 1 */
552  uint32 mode2; /**< \brief Parameter word 2 */
553  uint32 mode3; /**< \brief Parameter word 3 */
554  uint32 d1; /**< \brief Dummy value */
555  uint32 d2; /**< \brief Dummy value */
556  uint32 d3; /**< \brief Dummy value */
557  uint32 d4; /**< \brief Dummy value */
559 
560 /** \brief PVR polygon header with intensity color.
561 
562  This is the equivalent of pvr_poly_hdr_t, but for use with intensity color.
563 
564  \headerfile dc/pvr.h
565 */
566 typedef struct {
567  uint32 cmd; /**< \brief TA command */
568  uint32 mode1; /**< \brief Parameter word 1 */
569  uint32 mode2; /**< \brief Parameter word 2 */
570  uint32 mode3; /**< \brief Parameter word 3 */
571  float a; /**< \brief Face color alpha component */
572  float r; /**< \brief Face color red component */
573  float g; /**< \brief Face color green component */
574  float b; /**< \brief Face color blue component */
576 
577 /** \brief PVR polygon header to be used with modifier volumes.
578 
579  This is the equivalent of a pvr_poly_hdr_t for use when a polygon is to be
580  used with modifier volumes.
581 
582  \headerfile dc/pvr.h
583 */
584 typedef struct {
585  uint32 cmd; /**< \brief TA command */
586  uint32 mode1; /**< \brief Parameter word 1 */
587  uint32 mode2_0; /**< \brief Parameter word 2 (outside volume) */
588  uint32 mode3_0; /**< \brief Parameter word 3 (outside volume) */
589  uint32 mode2_1; /**< \brief Parameter word 2 (inside volume) */
590  uint32 mode3_1; /**< \brief Parameter word 3 (inside volume) */
591  uint32 d1; /**< \brief Dummy value */
592  uint32 d2; /**< \brief Dummy value */
594 
595 /** \brief PVR polygon header specifically for sprites.
596 
597  This is the equivalent of a pvr_poly_hdr_t for use when a quad/sprite is to
598  be rendered. Note that the color data is here, not in the vertices.
599 
600  \headerfile dc/pvr.h
601 */
602 typedef struct {
603  uint32 cmd; /**< \brief TA command */
604  uint32 mode1; /**< \brief Parameter word 1 */
605  uint32 mode2; /**< \brief Parameter word 2 */
606  uint32 mode3; /**< \brief Parameter word 3 */
607  uint32 argb; /**< \brief Sprite face color */
608  uint32 oargb; /**< \brief Sprite offset color */
609  uint32 d1; /**< \brief Dummy value */
610  uint32 d2; /**< \brief Dummy value */
612 
613 /** \brief Modifier volume header.
614 
615  This is the header that should be submitted when dealing with setting a
616  modifier volume.
617 
618  \headerfile dc/pvr.h
619 */
620 typedef struct {
621  uint32 cmd; /**< \brief TA command */
622  uint32 mode1; /**< \brief Parameter word 1 */
623  uint32 d1; /**< \brief Dummy value */
624  uint32 d2; /**< \brief Dummy value */
625  uint32 d3; /**< \brief Dummy value */
626  uint32 d4; /**< \brief Dummy value */
627  uint32 d5; /**< \brief Dummy value */
628  uint32 d6; /**< \brief Dummy value */
629 } pvr_mod_hdr_t;
630 
631 /** \brief Generic PVR vertex type.
632 
633  The PVR chip itself supports many more vertex types, but this is the main
634  one that can be used with both textured and non-textured polygons, and is
635  fairly fast.
636 
637  \headerfile dc/pvr.h
638 */
639 typedef struct {
640  uint32 flags; /**< \brief TA command (vertex flags) */
641  float x; /**< \brief X coordinate */
642  float y; /**< \brief Y coordinate */
643  float z; /**< \brief Z coordinate */
644  float u; /**< \brief Texture U coordinate */
645  float v; /**< \brief Texture V coordinate */
646  uint32 argb; /**< \brief Vertex color */
647  uint32 oargb; /**< \brief Vertex offset color */
648 } pvr_vertex_t;
649 
650 /** \brief PVR vertex type: Non-textured, packed color, affected by modifier
651  volume.
652 
653  This vertex type has two copies of colors. The second color is used when
654  enclosed within a modifier volume.
655 
656  \headerfile dc/pvr.h
657 */
658 typedef struct {
659  uint32 flags; /**< \brief TA command (vertex flags) */
660  float x; /**< \brief X coordinate */
661  float y; /**< \brief Y coordinate */
662  float z; /**< \brief Z coordinate */
663  uint32 argb0; /**< \brief Vertex color (outside volume) */
664  uint32 argb1; /**< \brief Vertex color (inside volume) */
665  uint32 d1; /**< \brief Dummy value */
666  uint32 d2; /**< \brief Dummy value */
668 
669 /** \brief PVR vertex type: Textured, packed color, affected by modifer volume.
670 
671  Note that this vertex type has two copies of colors, offset colors, and
672  texture coords. The second set of texture coords, colors, and offset colors
673  are used when enclosed within a modifer volume.
674 
675  \headerfile dc/pvr.h
676 */
677 typedef struct {
678  uint32 flags; /**< \brief TA command (vertex flags) */
679  float x; /**< \brief X coordinate */
680  float y; /**< \brief Y coordinate */
681  float z; /**< \brief Z coordinate */
682  float u0; /**< \brief Texture U coordinate (outside) */
683  float v0; /**< \brief Texture V coordinate (outside) */
684  uint32 argb0; /**< \brief Vertex color (outside) */
685  uint32 oargb0; /**< \brief Vertex offset color (outside) */
686  float u1; /**< \brief Texture U coordinate (inside) */
687  float v1; /**< \brief Texture V coordinate (inside) */
688  uint32 argb1; /**< \brief Vertex color (inside) */
689  uint32 oargb1; /**< \brief Vertex offset color (inside) */
690  uint32 d1; /**< \brief Dummy value */
691  uint32 d2; /**< \brief Dummy value */
692  uint32 d3; /**< \brief Dummy value */
693  uint32 d4; /**< \brief Dummy value */
695 
696 /** \brief PVR vertex type: Textured sprite.
697 
698  This vertex type is to be used with the sprite polygon header and the sprite
699  related commands to draw textured sprites. Note that there is no fourth Z
700  coordinate. I suppose it just gets interpolated?
701 
702  The U/V coordinates in here are in the 16-bit per coordinate form. Also,
703  like the fourth Z value, there is no fourth U or V, so it must get
704  interpolated from the others.
705 
706  \headerfile dc/pvr.h
707 */
708 typedef struct {
709  uint32 flags; /**< \brief TA command (vertex flags) */
710  float ax; /**< \brief First X coordinate */
711  float ay; /**< \brief First Y coordinate */
712  float az; /**< \brief First Z coordinate */
713  float bx; /**< \brief Second X coordinate */
714  float by; /**< \brief Second Y coordinate */
715  float bz; /**< \brief Second Z coordinate */
716  float cx; /**< \brief Third X coordinate */
717  float cy; /**< \brief Third Y coordinate */
718  float cz; /**< \brief Third Z coordinate */
719  float dx; /**< \brief Fourth X coordinate */
720  float dy; /**< \brief Fourth Y coordinate */
721  uint32 dummy; /**< \brief Dummy value */
722  uint32 auv; /**< \brief First U/V texture coordinates */
723  uint32 buv; /**< \brief Second U/V texture coordinates */
724  uint32 cuv; /**< \brief Third U/V texture coordinates */
726 
727 /** \brief PVR vertex type: Untextured sprite.
728 
729  This vertex type is to be used with the sprite polygon header and the sprite
730  related commands to draw untextured sprites (aka, quads).
731 */
732 typedef struct {
733  uint32 flags; /**< \brief TA command (vertex flags) */
734  float ax; /**< \brief First X coordinate */
735  float ay; /**< \brief First Y coordinate */
736  float az; /**< \brief First Z coordinate */
737  float bx; /**< \brief Second X coordinate */
738  float by; /**< \brief Second Y coordinate */
739  float bz; /**< \brief Second Z coordinate */
740  float cx; /**< \brief Third X coordinate */
741  float cy; /**< \brief Third Y coordinate */
742  float cz; /**< \brief Third Z coordinate */
743  float dx; /**< \brief Fourth X coordinate */
744  float dy; /**< \brief Fourth Y coordinate */
745  uint32 d1; /**< \brief Dummy value */
746  uint32 d2; /**< \brief Dummy value */
747  uint32 d3; /**< \brief Dummy value */
748  uint32 d4; /**< \brief Dummy value */
750 
751 /** \brief PVR vertex type: Modifier volume.
752 
753  This vertex type is to be used with the modifier volume header to specify
754  triangular modifier areas.
755 */
756 typedef struct {
757  uint32 flags; /**< \brief TA command (vertex flags) */
758  float ax; /**< \brief First X coordinate */
759  float ay; /**< \brief First Y coordinate */
760  float az; /**< \brief First Z coordinate */
761  float bx; /**< \brief Second X coordinate */
762  float by; /**< \brief Second Y coordinate */
763  float bz; /**< \brief Second Z coordinate */
764  float cx; /**< \brief Third X coordinate */
765  float cy; /**< \brief Third Y coordinate */
766  float cz; /**< \brief Third Z coordinate */
767  uint32 d1; /**< \brief Dummy value */
768  uint32 d2; /**< \brief Dummy value */
769  uint32 d3; /**< \brief Dummy value */
770  uint32 d4; /**< \brief Dummy value */
771  uint32 d5; /**< \brief Dummy value */
772  uint32 d6; /**< \brief Dummy value */
774 
775 /** \brief Pack four floating point color values into a 32-bit integer form.
776 
777  All of the color values should be between 0 and 1.
778 
779  \param a Alpha value
780  \param r Red value
781  \param g Green value
782  \param b Blue value
783  \return The packed color value
784 */
785 #define PVR_PACK_COLOR(a, r, g, b) ( \
786  ( ((uint8)( a * 255 ) ) << 24 ) | \
787  ( ((uint8)( r * 255 ) ) << 16 ) | \
788  ( ((uint8)( g * 255 ) ) << 8 ) | \
789  ( ((uint8)( b * 255 ) ) << 0 ) )
790 
791 /** \brief Pack two floating point coordinates into one 32-bit value,
792  truncating them to 16-bits each.
793 
794  \param u First coordinate to pack
795  \param v Second coordinate to pack
796  \return The packed coordinates
797 */
798 static inline uint32 PVR_PACK_16BIT_UV(float u, float v) {
799  return (((*((uint32 *) &u)) >> 0) & 0xFFFF0000) |
800  (((*((uint32 *) &v)) >> 16) & 0x0000FFFF);
801 }
802 
803 /* ... other vertex structs omitted for now ... */
804 
805 /** \defgroup pvr_commands TA command values
806 
807  These are are appropriate values for TA commands. Use whatever goes with the
808  primitive type you're using.
809 
810  @{
811 */
812 #define PVR_CMD_POLYHDR 0x80840000 /**< \brief PVR polygon header.
813 Striplength set to 2 */
814 #define PVR_CMD_VERTEX 0xe0000000 /**< \brief PVR vertex data */
815 #define PVR_CMD_VERTEX_EOL 0xf0000000 /**< \brief PVR vertex, end of strip */
816 #define PVR_CMD_USERCLIP 0x20000000 /**< \brief PVR user clipping area */
817 #define PVR_CMD_MODIFIER 0x80000000 /**< \brief PVR modifier volume */
818 #define PVR_CMD_SPRITE 0xA0000000 /**< \brief PVR sprite header */
819 /** @} */
820 
821 /** \defgroup pvr_bitmasks Constants and bitmasks for handling polygon
822  headers.
823 
824  Note that thanks to the arrangement of constants, this is mainly a matter of
825  bit shifting to compile headers...
826 
827  @{
828 */
829 #define PVR_TA_CMD_TYPE_SHIFT 24
830 #define PVR_TA_CMD_TYPE_MASK (7 << PVR_TA_CMD_TYPE_SHIFT)
831 
832 #define PVR_TA_CMD_USERCLIP_SHIFT 16
833 #define PVR_TA_CMD_USERCLIP_MASK (3 << PVR_TA_CMD_USERCLIP_SHIFT)
834 
835 #define PVR_TA_CMD_CLRFMT_SHIFT 4
836 #define PVR_TA_CMD_CLRFMT_MASK (7 << PVR_TA_CMD_CLRFMT_SHIFT)
837 
838 #define PVR_TA_CMD_SHADE_SHIFT 1
839 #define PVR_TA_CMD_SHADE_MASK (1 << PVR_TA_CMD_SHADE_SHIFT)
840 
841 #define PVR_TA_CMD_UVFMT_SHIFT 0
842 #define PVR_TA_CMD_UVFMT_MASK (1 << PVR_TA_CMD_UVFMT_SHIFT)
843 
844 #define PVR_TA_CMD_MODIFIER_SHIFT 7
845 #define PVR_TA_CMD_MODIFIER_MASK (1 << PVR_TA_CMD_MODIFIER_SHIFT)
846 
847 #define PVR_TA_CMD_MODIFIERMODE_SHIFT 6
848 #define PVR_TA_CMD_MODIFIERMODE_MASK (1 << PVR_TA_CMD_MODIFIERMODE_SHIFT)
849 
850 #define PVR_TA_PM1_DEPTHCMP_SHIFT 29
851 #define PVR_TA_PM1_DEPTHCMP_MASK (7 << PVR_TA_PM1_DEPTHCMP_SHIFT)
852 
853 #define PVR_TA_PM1_CULLING_SHIFT 27
854 #define PVR_TA_PM1_CULLING_MASK (3 << PVR_TA_PM1_CULLING_SHIFT)
855 
856 #define PVR_TA_PM1_DEPTHWRITE_SHIFT 26
857 #define PVR_TA_PM1_DEPTHWRITE_MASK (1 << PVR_TA_PM1_DEPTHWRITE_SHIFT)
858 
859 #define PVR_TA_PM1_TXRENABLE_SHIFT 25
860 #define PVR_TA_PM1_TXRENABLE_MASK (1 << PVR_TA_PM1_TXRENABLE_SHIFT)
861 
862 #define PVR_TA_PM1_MODIFIERINST_SHIFT 29
863 #define PVR_TA_PM1_MODIFIERINST_MASK (3 << PVR_TA_PM1_MODIFIERINST_SHIFT)
864 
865 #define PVR_TA_PM2_SRCBLEND_SHIFT 29
866 #define PVR_TA_PM2_SRCBLEND_MASK (7 << PVR_TA_PM2_SRCBLEND_SHIFT)
867 
868 #define PVR_TA_PM2_DSTBLEND_SHIFT 26
869 #define PVR_TA_PM2_DSTBLEND_MASK (7 << PVR_TA_PM2_DSTBLEND_SHIFT)
870 
871 #define PVR_TA_PM2_SRCENABLE_SHIFT 25
872 #define PVR_TA_PM2_SRCENABLE_MASK (1 << PVR_TA_PM2_SRCENABLE_SHIFT)
873 
874 #define PVR_TA_PM2_DSTENABLE_SHIFT 24
875 #define PVR_TA_PM2_DSTENABLE_MASK (1 << PVR_TA_PM2_DSTENABLE_SHIFT)
876 
877 #define PVR_TA_PM2_FOG_SHIFT 22
878 #define PVR_TA_PM2_FOG_MASK (3 << PVR_TA_PM2_FOG_SHIFT)
879 
880 #define PVR_TA_PM2_CLAMP_SHIFT 21
881 #define PVR_TA_PM2_CLAMP_MASK (1 << PVR_TA_PM2_CLAMP_SHIFT)
882 
883 #define PVR_TA_PM2_ALPHA_SHIFT 20
884 #define PVR_TA_PM2_ALPHA_MASK (1 << PVR_TA_PM2_ALPHA_SHIFT)
885 
886 #define PVR_TA_PM2_TXRALPHA_SHIFT 19
887 #define PVR_TA_PM2_TXRALPHA_MASK (1 << PVR_TA_PM2_TXRALPHA_SHIFT)
888 
889 #define PVR_TA_PM2_UVFLIP_SHIFT 17
890 #define PVR_TA_PM2_UVFLIP_MASK (3 << PVR_TA_PM2_UVFLIP_SHIFT)
891 
892 #define PVR_TA_PM2_UVCLAMP_SHIFT 15
893 #define PVR_TA_PM2_UVCLAMP_MASK (3 << PVR_TA_PM2_UVCLAMP_SHIFT)
894 
895 #define PVR_TA_PM2_FILTER_SHIFT 12
896 #define PVR_TA_PM2_FILTER_MASK (7 << PVR_TA_PM2_FILTER_SHIFT)
897 
898 #define PVR_TA_PM2_MIPBIAS_SHIFT 8
899 #define PVR_TA_PM2_MIPBIAS_MASK (15 << PVR_TA_PM2_MIPBIAS_SHIFT)
900 
901 #define PVR_TA_PM2_TXRENV_SHIFT 6
902 #define PVR_TA_PM2_TXRENV_MASK (3 << PVR_TA_PM2_TXRENV_SHIFT)
903 
904 #define PVR_TA_PM2_USIZE_SHIFT 3
905 #define PVR_TA_PM2_USIZE_MASK (7 << PVR_TA_PM2_USIZE_SHIFT)
906 
907 #define PVR_TA_PM2_VSIZE_SHIFT 0
908 #define PVR_TA_PM2_VSIZE_MASK (7 << PVR_TA_PM2_VSIZE_SHIFT)
909 
910 #define PVR_TA_PM3_MIPMAP_SHIFT 31
911 #define PVR_TA_PM3_MIPMAP_MASK (1 << PVR_TA_PM3_MIPMAP_SHIFT)
912 
913 #define PVR_TA_PM3_TXRFMT_SHIFT 0
914 #define PVR_TA_PM3_TXRFMT_MASK 0xffffffff
915 /** @} */
916 
917 /**** Register macros ***************************************************/
918 
919 /* We use these macros to do all PVR register access, so that it's
920  simple later on to hook them for debugging or whatnot. */
921 
922 /** \brief Retrieve a PVR register value
923  \param REG The register to fetch
924  \return The value of that register (32-bits)
925 */
926 #define PVR_GET(REG) (* ( (uint32*)( 0xa05f8000 + (REG) ) ) )
927 
928 /** \brief Set a PVR register value
929  \param REG The register to set
930  \param VALUE The value to set in the register (32-bits)
931 */
932 #define PVR_SET(REG, VALUE) PVR_GET(REG) = (VALUE)
933 
934 /* The registers themselves; these are from Maiwe's powervr-reg.txt */
935 /* Note that 2D specific registers have been excluded for now (like
936  vsync, hsync, v/h size, etc) */
937 
938 /** \defgroup pvr_regs Offsets to registers of the PVR
939  @{
940 */
941 #define PVR_ID 0x0000 /**< \brief Chip ID */
942 #define PVR_REVISION 0x0004 /**< \brief Chip revision */
943 #define PVR_RESET 0x0008 /**< \brief Reset pins */
944 #define PVR_ISP_START 0x0014 /**< \brief Start the ISP/TSP */
945 #define PVR_UNK_0018 0x0018 /**< \brief ?? */
946 #define PVR_ISP_VERTBUF_ADDR 0x0020 /**< \brief Vertex buffer address for scene rendering */
947 #define PVR_ISP_TILEMAT_ADDR 0x002c /**< \brief Tile matrix address for scene rendering */
948 #define PVR_SPANSORT_CFG 0x0030 /**< \brief ?? -- write 0x101 for now */
949 #define PVR_FB_CFG_1 0x0044 /**< \brief Framebuffer config 1 */
950 #define PVR_FB_CFG_2 0x0048 /**< \brief Framebuffer config 2 */
951 #define PVR_RENDER_MODULO 0x004c /**< \brief Render modulo */
952 #define PVR_RENDER_ADDR 0x0060 /**< \brief Render output address */
953 #define PVR_RENDER_ADDR_2 0x0064 /**< \brief Output for strip-buffering */
954 #define PVR_PCLIP_X 0x0068 /**< \brief Horizontal clipping area */
955 #define PVR_PCLIP_Y 0x006c /**< \brief Vertical clipping area */
956 #define PVR_CHEAP_SHADOW 0x0074 /**< \brief Cheap shadow control */
957 #define PVR_OBJECT_CLIP 0x0078 /**< \brief Distance for polygon culling */
958 #define PVR_UNK_007C 0x007c /**< \brief ?? -- write 0x0027df77 for now */
959 #define PVR_UNK_0080 0x0080 /**< \brief ?? -- write 7 for now */
960 #define PVR_TEXTURE_CLIP 0x0084 /**< \brief Distance for texture clipping */
961 #define PVR_BGPLANE_Z 0x0088 /**< \brief Distance for background plane */
962 #define PVR_BGPLANE_CFG 0x008c /**< \brief Background plane config */
963 #define PVR_UNK_0098 0x0098 /**< \brief ?? -- write 0x00800408 for now */
964 #define PVR_UNK_00A0 0x00a0 /**< \brief ?? -- write 0x20 for now */
965 #define PVR_UNK_00A8 0x00a8 /**< \brief ?? -- write 0x15d1c951 for now */
966 #define PVR_FOG_TABLE_COLOR 0x00b0 /**< \brief Table fog color */
967 #define PVR_FOG_VERTEX_COLOR 0x00b4 /**< \brief Vertex fog color */
968 #define PVR_FOG_DENSITY 0x00b8 /**< \brief Fog density coefficient */
969 #define PVR_COLOR_CLAMP_MAX 0x00bc /**< \brief RGB Color clamp max */
970 #define PVR_COLOR_CLAMP_MIN 0x00c0 /**< \brief RGB Color clamp min */
971 #define PVR_GUN_POS 0x00c4 /**< \brief Light gun position */
972 #define PVR_UNK_00C8 0x00c8 /**< \brief ?? -- write same as border H in 00d4 << 16 */
973 #define PVR_VPOS_IRQ 0x00cc /**< \brief Vertical position IRQ */
974 #define PVR_TEXTURE_MODULO 0x00e4 /**< \brief Output texture width modulo */
975 #define PVR_VIDEO_CFG 0x00e8 /**< \brief Misc video config */
976 #define PVR_SCALER_CFG 0x00f4 /**< \brief Smoothing scaler */
977 #define PVR_PALETTE_CFG 0x0108 /**< \brief Palette format */
978 #define PVR_SYNC_STATUS 0x010c /**< \brief V/H blank status */
979 #define PVR_UNK_0110 0x0110 /**< \brief ?? -- write 0x93f39 for now */
980 #define PVR_UNK_0114 0x0114 /**< \brief ?? -- write 0x200000 for now */
981 #define PVR_UNK_0118 0x0118 /**< \brief ?? -- write 0x8040 for now */
982 #define PVR_TA_OPB_START 0x0124 /**< \brief Object Pointer Buffer start for TA usage */
983 #define PVR_TA_VERTBUF_START 0x0128 /**< \brief Vertex buffer start for TA usage */
984 #define PVR_TA_OPB_END 0x012c /**< \brief OPB end for TA usage */
985 #define PVR_TA_VERTBUF_END 0x0130 /**< \brief Vertex buffer end for TA usage */
986 #define PVR_TA_OPB_POS 0x0134 /**< \brief Top used memory location in OPB for TA usage */
987 #define PVR_TA_VERTBUF_POS 0x0138 /**< \brief Top used memory location in vertbuf for TA usage */
988 #define PVR_TILEMAT_CFG 0x013c /**< \brief Tile matrix size config */
989 #define PVR_OPB_CFG 0x0140 /**< \brief Active lists / list size */
990 #define PVR_TA_INIT 0x0144 /**< \brief Initialize vertex reg. params */
991 #define PVR_YUV_ADDR 0x0148 /**< \brief YUV conversion destination */
992 #define PVR_YUV_CFG_1 0x014c /**< \brief YUV configuration */
993 #define PVR_UNK_0160 0x0160 /**< \brief ?? */
994 #define PVR_TA_OPB_INIT 0x0164 /**< \brief Object pointer buffer position init */
995 #define PVR_FOG_TABLE_BASE 0x0200 /**< \brief Base of the fog table */
996 #define PVR_PALETTE_TABLE_BASE 0x1000 /**< \brief Base of the palette table */
997 /** @} */
998 
999 /* Useful memory locations */
1000 #define PVR_TA_INPUT 0x10000000 /**< \brief TA command input */
1001 #define PVR_RAM_BASE 0xa5000000 /**< \brief PVR RAM (raw) */
1002 #define PVR_RAM_INT_BASE 0xa4000000 /**< \brief PVR RAM (interleaved) */
1003 
1004 #define PVR_RAM_SIZE (8*1024*1024) /**< \brief RAM size in bytes */
1005 
1006 #define PVR_RAM_TOP (PVR_RAM_BASE + PVR_RAM_SIZE) /**< \brief Top of raw PVR RAM */
1007 #define PVR_RAM_INT_TOP (PVR_RAM_INT_BASE + PVR_RAM_SIZE) /**< \brief Top of int PVR RAM */
1008 
1009 /* Register content defines, as needed; these will be filled in over time
1010  as the implementation requires them. There's too many to do otherwise. */
1011 
1012 /** \defgroup pvr_reset_vals Values used to reset parts of the PVR
1013 
1014  These values are written to the PVR_RESET register in order to reset the
1015  system or to take it out of reset.
1016 
1017  @{
1018 */
1019 #define PVR_RESET_ALL 0xffffffff /**< \brief Reset the wole PVR */
1020 #define PVR_RESET_NONE 0x00000000 /**< \brief Cancel reset state */
1021 #define PVR_RESET_TA 0x00000001 /**< \brief Reset only the TA */
1022 #define PVR_RESET_ISPTSP 0x00000002 /**< \brief Reset only the ISP/TSP */
1023 /** @} */
1024 
1025 #define PVR_ISP_START_GO 0xffffffff /**< \brief Write to the PVR_ISP_START register to start rendering */
1026 
1027 #define PVR_TA_INIT_GO 0x80000000 /**< \brief Write to the PVR_TA_INIT register to confirm settings */
1028 
1029 
1030 /* Initialization ****************************************************/
1031 
1032 /* Initialization and shutdown: stuff you should only ever have to do
1033  once in your program. */
1034 
1035 /** \defgroup pvr_binsizes Available sizes for primitive bins
1036  @{
1037 */
1038 #define PVR_BINSIZE_0 0 /**< \brief 0-length (disables the list) */
1039 #define PVR_BINSIZE_8 8 /**< \brief 8-word (32-byte) length */
1040 #define PVR_BINSIZE_16 16 /**< \brief 16-word (64-byte) length */
1041 #define PVR_BINSIZE_32 32 /**< \brief 32-word (128-byte) length */
1042 /** @} */
1043 
1044 /** \brief PVR initialization structure
1045 
1046  This structure defines how the PVR initializes various parts of the system,
1047  including the primitive bin sizes, the vertex buffer size, and whether
1048  vertex DMA will be enabled.
1049 
1050  You essentially fill one of these in, and pass it to pvr_init().
1051 
1052  \headerfile dc/pvr.h
1053 */
1054 typedef struct {
1055  /** \brief Bin sizes.
1056 
1057  The bins go in the following order: opaque polygons, opaque modifiers,
1058  translucent polygons, translucent modifiers, punch-thrus
1059  */
1060  int opb_sizes[5];
1061 
1062  /** \brief Vertex buffer size (should be a nice round number) */
1064 
1065  /** \brief Enable vertex DMA?
1066 
1067  Set to non-zero if we want to enable vertex DMA mode. Note that if this
1068  is set, then _all_ enabled lists need to have a vertex buffer assigned,
1069  even if you never use that list for anything.
1070  */
1072 
1073  /** \brief Enable horizontal scaling?
1074 
1075  Set to non-zero if horizontal scaling is to be enabled. By enabling this
1076  setting and stretching your image to double the native screen width, you
1077  can get horizontal full-screen anti-aliasing. */
1080 
1081 /** \brief Initialize the PVR chip to ready status.
1082 
1083  This function enables the specified lists and uses the specified parameters.
1084  Note that bins and vertex buffers come from the texture memory pool, so only
1085  allocate what you actually need. Expects that a 2D mode was initialized
1086  already using the vid_* API.
1087 
1088  \param params The set of parameters to initialize with
1089  \retval 0 On success
1090  \retval -1 If the PVR has already been initialized or the video
1091  mode active is not suitable for 3D
1092 */
1093 int pvr_init(pvr_init_params_t *params);
1094 
1095 /** \brief Simple PVR initialization.
1096 
1097  This simpler function initializes the PVR using 16/16 for the opaque
1098  and translucent lists' bin sizes, and 0's for everything else. It sets 512KB
1099  of vertex buffer. This is equivalent to the old ta_init_defaults() for now.
1100 
1101  \retval 0 On success
1102  \retval -1 If the PVR has already been initialized or the video
1103  mode active is not suitable for 3D
1104 */
1105 int pvr_init_defaults();
1106 
1107 /** \brief Shut down the PVR chip from ready status.
1108 
1109  This essentially leaves the video system in 2D mode as it was before the
1110  init.
1111 
1112  \retval 0 On success
1113  \retval -1 If the PVR has not been initialized
1114 */
1115 int pvr_shutdown();
1116 
1117 
1118 /* Misc parameters ***************************************************/
1119 
1120 /* These are miscellaneous parameters you can set which affect the
1121  rendering process. */
1122 
1123 /** \brief Set the background plane color.
1124 
1125  This function sets the color of the area of the screen not covered by any
1126  other polygons.
1127 
1128  \param r Red component of the color to set
1129  \param g Green component of the color to set
1130  \param b Blue component of the color to set
1131 */
1132 void pvr_set_bg_color(float r, float g, float b);
1133 
1134 /** \brief Retrieve the current VBlank count.
1135 
1136  This function retrieves the number of VBlank interrupts that have occurred
1137  since the PVR was initialized.
1138 
1139  \return The number of VBlanks since init
1140 */
1141 int pvr_get_vbl_count();
1142 
1143 /* Statistics structure */
1144 /** \brief PVR statistics structure.
1145 
1146  This structure is used to hold various statistics about the operation of the
1147  PVR since initialization.
1148 
1149  \headerfile dc/pvr.h
1150 */
1151 typedef struct pvr_stats {
1152  uint32 enabled_list_mask; /**< \brief Which lists are enabled? */
1153  uint32 vbl_count; /**< \brief VBlank count */
1154  int frame_last_time; /**< \brief Ready-to-Ready length for the last frame in milliseconds */
1155  float frame_rate; /**< \brief Current frame rate (per second) */
1156  int reg_last_time; /**< \brief Registration time for the last frame in milliseconds */
1157  int rnd_last_time; /**< \brief Rendering time for the last frame in milliseconds */
1158  int vtx_buffer_used; /**< \brief Number of bytes used in the vertex buffer for the last frame */
1159  int vtx_buffer_used_max;/**< \brief Number of bytes used in the vertex buffer for the largest frame */
1160  int buf_last_time; /**< \brief DMA buffer file time for the last frame in milliseconds */
1161  uint32 frame_count; /**< \brief Total number of rendered/viewed frames */
1162  /* ... more later as it's implemented ... */
1163 } pvr_stats_t;
1164 
1165 /** \brief Get the current statistics from the PVR.
1166 
1167  This function fills in the pvr_stats_t structure passed in with the current
1168  statistics of the system.
1169 
1170  \param stat The statistics structure to fill in. Must not be
1171  NULL
1172  \retval 0 On success
1173  \retval -1 If the PVR is not initialized
1174 */
1175 int pvr_get_stats(pvr_stats_t *stat);
1176 
1177 
1178 /* Palette management ************************************************/
1179 
1180 /* In addition to its 16-bit truecolor modes, the PVR also supports some
1181  nice paletted modes. These aren't useful for super high quality images
1182  most of the time, but they can be useful for doing some interesting
1183  special effects, like the old cheap "worm hole". */
1184 
1185 /** \defgroup pvr_palfmts PVR palette formats
1186 
1187  Entries in the PVR's palettes can be of any of these formats. Note that you
1188  can only have one format active at a time.
1189 
1190  @{
1191 */
1192 #define PVR_PAL_ARGB1555 0 /**< \brief 16-bit ARGB1555 palette format */
1193 #define PVR_PAL_RGB565 1 /**< \brief 16-bit RGB565 palette format */
1194 #define PVR_PAL_ARGB4444 2 /**< \brief 16-bit ARGB4444 palette format */
1195 #define PVR_PAL_ARGB8888 3 /**< \brief 32-bit ARGB8888 palette format */
1196 /** @} */
1197 
1198 /** \brief Set the palette format.
1199 
1200  This function sets the currently active palette format on the PVR. Each
1201  entry in the palette table is 32-bits in length, regardless of what color
1202  format is in use.
1203 
1204  Be sure to use care when using the PVR_PAL_ARGB8888 format. Rendering speed
1205  is greatly affected (cut about in half) if you use any filtering with
1206  paletted textures with ARGB8888 entries in the palette.
1207 
1208  \param fmt The format to use
1209  \see pvr_palfmts
1210 */
1211 void pvr_set_pal_format(int fmt);
1212 
1213 /** \brief Set a palette value.
1214 
1215  Note that while the color format is variable, each entry is still 32-bits in
1216  length regardless (and you only get a total of 1024 of them). If using one
1217  of the 16-bit palette formats, only the low-order 16-bits of the entry are
1218  valid, and the high bits should be filled in with 0.
1219 
1220  \param idx The index to set to (0-1023)
1221  \param value The color value to set in that palette entry
1222 */
1223 static inline void pvr_set_pal_entry(uint32 idx, uint32 value) {
1224  PVR_SET(PVR_PALETTE_TABLE_BASE + 4 * idx, value);
1225 }
1226 
1227 
1228 /* Hardware Fog parameters *******************************************/
1229 
1230 /* Thanks to Paul Boese for figuring this stuff out */
1231 
1232 /** \brief Set the table fog color.
1233 
1234  This function sets the color of fog for table fog. 0-1 range for all colors.
1235 
1236  \param a Alpha value of the fog
1237  \param r Red value of the fog
1238  \param g Green value of the fog
1239  \param b Blue value of the fog
1240 */
1241 void pvr_fog_table_color(float a, float r, float g, float b);
1242 
1243 /** \brief Set the vertex fog color.
1244 
1245  This function sets the fog color for vertex fog. 0-1 range for all colors.
1246  This function is currently not implemented, as vertex fog is not supported
1247  by KOS. Calling this function will cause an assertion failure.
1248 
1249  \param a Alpha value of the fog
1250  \param r Red value of the fog
1251  \param g Green value of the fog
1252  \param b Blue value of the fog
1253 */
1254 void pvr_fog_vertex_color(float a, float r, float g, float b);
1255 
1256 /** \brief Set the fog far depth.
1257 
1258  This function sets the PVR_FOG_DENSITY register appropriately for the
1259  specified value.
1260 
1261  \param d The depth to set
1262 */
1263 void pvr_fog_far_depth(float d);
1264 
1265 /** \brief Initialize the fog table using an exp2 algorithm (like GL_EXP2).
1266 
1267  This function will automatically set the PVR_FOG_DENSITY register to
1268  259.999999 as a part of its processing, then set up the fog table.
1269 
1270  \param density Fog density value
1271 */
1272 void pvr_fog_table_exp2(float density);
1273 
1274 /** \brief Initialize the fog table using an exp algorithm (like GL_EXP).
1275 
1276  This function will automatically set the PVR_FOG_DENSITY register to
1277  259.999999 as a part of its processing, then set up the fog table.
1278 
1279  \param density Fog density value
1280 */
1281 void pvr_fog_table_exp(float density);
1282 
1283 /** \brief Initialize the fog table using a linear algorithm (like GL_LINEAR).
1284 
1285  This function will set the PVR_FOG_DENSITY register to the as appropriate
1286  for the end value, and initialize the fog table for perspectively correct
1287  linear fog.
1288 
1289  \param start Fog start point
1290  \param end Fog end point
1291 */
1292 void pvr_fog_table_linear(float start, float end);
1293 
1294 /** \brief Set a custom fog table from float values
1295 
1296  This function allows you to specify whatever values you need to for your fog
1297  parameters. All values should be clamped between 0 and 1, and its your
1298  responsibility to set up the PVR_FOG_DENSITY register by calling
1299  pvr_fog_far_depth() with an appropriate value. The table passed in should
1300  have 129 entries, where the 0th entry is farthest from the eye and the last
1301  entry is nearest. Higher values = heavier fog.
1302 
1303  \param tbl1 The table of fog values to set
1304 */
1305 void pvr_fog_table_custom(float tbl1[]);
1306 
1307 
1308 /* Memory management *************************************************/
1309 
1310 /* PVR memory management in KOS uses a modified dlmalloc; see the
1311  source file pvr_mem_core.c for more info. */
1312 
1313 /** \brief Allocate a chunk of memory from texture space.
1314 
1315  This function acts as the memory allocator for the PVR texture RAM pool. It
1316  acts exactly as one would expect a malloc() function to act, returning a
1317  normal pointer that can be directly written to if one desires to do so. All
1318  allocations will be aligned to a 32-byte boundary.
1319 
1320  \param size The amount of memory to allocate
1321  \return A pointer to the memory on success, NULL on error
1322 */
1323 pvr_ptr_t pvr_mem_malloc(size_t size);
1324 
1325 /** \brief Free a block of allocated memory in the PVR RAM pool.
1326 
1327  This function frees memory previously allocated with pvr_mem_malloc().
1328 
1329  \param chunk The location of the start of the block to free
1330 */
1331 void pvr_mem_free(pvr_ptr_t chunk);
1332 
1333 /** \brief Return the number of bytes available still in the PVR RAM pool.
1334  \return The number of bytes available
1335 */
1337 
1338 /** \brief Reset the PVR RAM pool.
1339 
1340  This will essentially free any blocks allocated within the pool. There's
1341  generally not many good reasons for doing this.
1342 */
1343 void pvr_mem_reset();
1344 
1345 /** \brief Print the list of allocated blocks in the PVR RAM pool.
1346 
1347  This function only works if you've enabled KM_DBG in pvr_mem.c.
1348 */
1349 void pvr_mem_print_list();
1350 
1351 /** \brief Print statistics about the PVR RAM pool.
1352 
1353  This prints out statistics like what malloc_stats() provides. Also, if
1354  KM_DBG is enabled in pvr_mem.c, it prints the list of allocated blocks.
1355 */
1356 void pvr_mem_stats();
1357 
1358 /* Scene rendering ***************************************************/
1359 
1360 /* This API is used to submit triangle strips to the PVR via the TA
1361  interace in the chip.
1362 
1363  An important side note about the PVR is that all primitive types
1364  must be submitted grouped together. If you have 10 polygons for each
1365  list type, then the PVR must receive them via the TA by list type,
1366  with a list delimiter in between.
1367 
1368  So there are two modes you can use here. The first mode allows you to
1369  submit data directly to the TA. Your data will be forwarded to the
1370  chip for processing as it is fed to the PVR module. If your data
1371  is easily sorted into the primitive types, then this is the fastest
1372  mode for submitting data.
1373 
1374  The second mode allows you to submit data via main-RAM vertex buffers,
1375  which will be queued until the proper primitive type is active. In this
1376  case, each piece of data is copied into the vertex buffer while the
1377  wrong list is activated, and when the proper list becomes activated,
1378  the data is all sent at once. Ideally this would be via DMA, right
1379  now it is by store queues. This has the advantage of allowing you to
1380  send data in any order and have the PVR functions resolve how it should
1381  get sent to the hardware, but it is slower.
1382 
1383  The nice thing is that any combination of these modes can be used. You
1384  can assign a vertex buffer for any list, and it will be used to hold the
1385  incoming vertex data until the proper list has come up. Or if the proper
1386  list is already up, the data will be submitted directly. So if most of
1387  your polygons are opaque, and you only have a couple of translucents,
1388  you can set a small buffer to gather translucent data and then it will
1389  get sent when you do a pvr_end_scene().
1390 
1391  Thanks to Mikael Kalms for the idea for this API.
1392 
1393  Another somewhat subtle point that bears mentioning is that in the normal
1394  case (interrupts enabled) an interrupt handler will automatically take
1395  care of starting a frame rendering (after scene_finish()) and also
1396  flipping pages when appropriate. */
1397 
1398 /** \brief Is vertex DMA enabled?
1399  \return Non-zero if vertex DMA was enabled at init time
1400 */
1402 
1403 /** \brief Setup a vertex buffer for one of the list types.
1404 
1405  If the specified list type already has a vertex buffer, it will be replaced
1406  by the new one. Note that each buffer should actually be twice as long as
1407  what you will need to hold two frames worth of data).
1408 
1409  You should generally not try to do this at any time besides before a frame
1410  is begun, or Bad Things May Happen.
1411 
1412  \param list The primitive list to set the buffer for.
1413  \param buffer The location of the buffer in main RAM. This must be
1414  aligned to a 32-byte boundary.
1415  \param len The length of the buffer. This must be a multiple of
1416  64, and must be at least 128 (even if you're not
1417  using the list).
1418  \return The old buffer location (if any)
1419 */
1420 void * pvr_set_vertbuf(pvr_list_t list, void * buffer, int len);
1421 
1422 /** \brief Retrieve a pointer to the current output location in the DMA buffer
1423  for the requested list.
1424 
1425  Vertex DMA must globally be enabled for this to work. Data may be added to
1426  this buffer by the user program directly; however, make sure to call
1427  pvr_vertbuf_written() to notify the system of any such changes.
1428 
1429  \param list The primitive list to get the buffer for.
1430  \return The tail of that list's buffer.
1431 */
1432 void * pvr_vertbuf_tail(pvr_list_t list);
1433 
1434 /** \brief Notify the PVR system that data have been written into the output
1435  buffer for the given list.
1436 
1437  This should always be done after writing data directly to these buffers or
1438  it will get overwritten by other data.
1439 
1440  \param list The primitive list that was modified.
1441  \param amt Number of bytes written. Must be a multiple of 32.
1442 */
1443 void pvr_vertbuf_written(pvr_list_t list, uint32 amt);
1444 
1445 /** \brief Begin collecting data for a frame of 3D output to the off-screen
1446  frame buffer.
1447 
1448  You must call this function (or pvr_scene_begin_txr()) for ever frame of
1449  output.
1450 */
1451 void pvr_scene_begin();
1452 
1453 /** \brief Begin collecting data for a frame of 3D output to the specified
1454  texture.
1455 
1456  This function currently only supports outputting at the same size as the
1457  actual screen. Thus, make sure rx and ry are at least large enough for that.
1458  For a 640x480 output, rx will generally be 1024 on input and ry 512, as
1459  these are the smallest values that are powers of two and will hold the full
1460  screen sized output.
1461 
1462  \param txr The texture to render to.
1463  \param rx Width of the texture buffer (in pixels).
1464  \param ry Height of the texture buffer (in pixels).
1465 */
1466 void pvr_scene_begin_txr(pvr_ptr_t txr, uint32 *rx, uint32 *ry);
1467 
1468 /** \brief Begin collecting data for the given list type.
1469 
1470  Lists do not have to be submitted in any particular order, but all types of
1471  a list must be submitted at once (unless vertex DMA mode is enabled).
1472 
1473  Note that there is no need to call this function in DMA mode unless you want
1474  to make use of pvr_prim() for compatibility. This function will
1475  automatically call pvr_list_finish() if a list is already opened before
1476  opening the new list.
1477 
1478  \param list The list to open.
1479  \retval 0 On success.
1480  \retval -1 If the specified list has already been closed.
1481 */
1482 int pvr_list_begin(pvr_list_t list);
1483 
1484 /** \brief End collecting data for the current list type.
1485 
1486  Lists can never be opened again within a single frame once they have been
1487  closed. Thus submitting a primitive that belongs in a closed list is
1488  considered an error. Closing a list that is already closed is also an error.
1489 
1490  Note that if you open a list but do not submit any primitives, a blank one
1491  will be submitted to satisfy the hardware. If vertex DMA mode is enabled,
1492  then this simply sets the current list pointer to no list, and none of the
1493  above restrictions apply.
1494 
1495  \retval 0 On success.
1496  \retval -1 On error.
1497 */
1498 int pvr_list_finish();
1499 
1500 /** \brief Submit a primitive of the current list type.
1501 
1502  Note that any values submitted in this fashion will go directly to the
1503  hardware without any sort of buffering, and submitting a primitive of the
1504  wrong type will quite likely ruin your scene. Note that this also will not
1505  work if you haven't begun any list types (i.e., all data is queued). If DMA
1506  is enabled, the primitive will be appended to the end of the currently
1507  selected list's buffer.
1508 
1509  \param data The primitive to submit.
1510  \param size The length of the primitive, in bytes. Must be a
1511  multiple of 32.
1512  \retval 0 On success.
1513  \retval -1 On error.
1514 */
1515 int pvr_prim(void * data, int size);
1516 
1517 /** \brief Direct Rendering state variable type. */
1519 
1520 /** \brief Initialize a state variable for Direct Rendering.
1521 
1522  \param vtx_buf_ptr A variable of type pvr_dr_state_t to init.
1523 */
1524 #define pvr_dr_init(vtx_buf_ptr) do { \
1525  (vtx_buf_ptr) = 0; \
1526  QACR0 = ((((uint32)PVR_TA_INPUT) >> 26) << 2) & 0x1c; \
1527  QACR1 = ((((uint32)PVR_TA_INPUT) >> 26) << 2) & 0x1c; \
1528  } while (0)
1529 
1530 /** \brief Obtain the target address for Direct Rendering.
1531 
1532  \param vtx_buf_ptr State variable for Direct Rendering. Should be of
1533  type pvr_dr_state_t, and must have been initialized
1534  previously in the scene with pvr_dr_init().
1535  \return A write-only destination address where a primitive
1536  should be written to get ready to submit it to the
1537  TA in DR mode.
1538 */
1539 #define pvr_dr_target(vtx_buf_ptr) \
1540  ({ (vtx_buf_ptr) ^= 32; \
1541  (pvr_vertex_t *)(0xe0000000 | (vtx_buf_ptr)); \
1542  })
1543 
1544 /** \brief Commit a primitive written into the Direct Rendering target address.
1545 
1546  \param addr The address returned by pvr_dr_target(), after you
1547  have written the primitive to it.
1548 */
1549 #define pvr_dr_commit(addr) __asm__ __volatile__("pref @%0" : : "r" (addr))
1550 
1551 /** \brief Submit a primitive of the given list type.
1552 
1553  Data will be queued in a vertex buffer, thus one must be available for the
1554  list specified (will be asserted by the code).
1555 
1556  \param list The list to submit to.
1557  \param data The primitive to submit.
1558  \param size The size of the primitive in bytes. This must be a
1559  multiple of 32.
1560  \retval 0 On success.
1561  \retval -1 On error.
1562 */
1563 int pvr_list_prim(pvr_list_t list, void * data, int size);
1564 
1565 /** \brief Flush the buffered data of the given list type to the TA.
1566 
1567  This function is currently not implemented, and calling it will result in an
1568  assertion failure. It is intended to be used later in a "hybrid" mode where
1569  both direct and DMA TA submission is possible.
1570 
1571  \param list The list to flush.
1572  \retval -1 On error (it is not possible to succeed).
1573 */
1574 int pvr_list_flush(pvr_list_t list);
1575 
1576 /** \brief Call this after you have finished submitting all data for a frame.
1577 
1578  Once this has been called, you can not submit any more data until one of the
1579  pvr_scene_begin() or pvr_scene_begin_txr() functions is called again.
1580 
1581  \retval 0 On success.
1582  \retval -1 On error (no scene started).
1583 */
1584 int pvr_scene_finish();
1585 
1586 /** \brief Block the caller until the PVR system is ready for another frame to
1587  be submitted.
1588 
1589  The PVR system allocates enough space for two frames: one in data collection
1590  mode, and another in rendering mode. If a frame is currently rendering, and
1591  another frame has already been closed, then the caller cannot do anything
1592  else until the rendering frame completes. Note also that the new frame
1593  cannot be activated except during a vertical blanking period, so this
1594  essentially waits until a rendered frame is complete and a vertical blank
1595  happens.
1596 
1597  \retval 0 On success. A new scene can be started now.
1598  \retval -1 On error. Something is probably very wrong...
1599 */
1600 int pvr_wait_ready();
1601 
1602 /** \brief Check if the PVR system is ready for another frame to be submitted.
1603 
1604  \retval 0 If the PVR is ready for a new scene. You must call
1605  pvr_wait_ready() afterwards, before starting a new
1606  scene.
1607  \retval -1 If the PVR is not ready for a new scene yet.
1608 */
1609 int pvr_check_ready();
1610 
1611 
1612 /* Primitive handling ************************************************/
1613 
1614 /* These functions help you prepare primitives for loading into the
1615  PVR for scene processing. */
1616 
1617 /** \brief Compile a polygon context into a polygon header.
1618 
1619  This function compiles a pvr_poly_cxt_t into the form needed by the hardware
1620  for rendering. This is for use with normal polygon headers.
1621 
1622  \param dst Where to store the compiled header.
1623  \param src The context to compile.
1624 */
1626 
1627 /** \brief Fill in a polygon context for non-textured polygons.
1628 
1629  This function fills in a pvr_poly_cxt_t with default parameters appropriate
1630  for rendering a non-textured polygon in the given list.
1631 
1632  \param dst Where to store the polygon context.
1633  \param list The primitive list to be used.
1634 */
1635 void pvr_poly_cxt_col(pvr_poly_cxt_t *dst, pvr_list_t list);
1636 
1637 /** \brief Fill in a polygon context for a textured polygon.
1638 
1639  This function fills in a pvr_poly_cxt_t with default parameters appropriate
1640  for rendering a textured polygon in the given list.
1641 
1642  \param dst Where to store the polygon context.
1643  \param list The primitive list to be used.
1644  \param textureformat The format of the texture used.
1645  \param tw The width of the texture, in pixels.
1646  \param th The height of the texture, in pixels.
1647  \param textureaddr A pointer to the texture.
1648  \param filtering The type of filtering to use.
1649 
1650  \see pvr_txr_fmts
1651  \see pvr_filter_modes
1652 */
1654  int textureformat, int tw, int th, pvr_ptr_t textureaddr,
1655  int filtering);
1656 
1657 /** \brief Compile a sprite context into a sprite header.
1658 
1659  This function compiles a pvr_sprite_cxt_t into the form needed by the
1660  hardware for rendering. This is for use with sprite headers.
1661 
1662  \param dst Where to store the compiled header.
1663  \param src The context to compile.
1664 */
1666  pvr_sprite_cxt_t *src);
1667 
1668 /** \brief Fill in a sprite context for non-textured sprites.
1669 
1670  This function fills in a pvr_sprite_cxt_t with default parameters
1671  appropriate for rendering a non-textured sprite in the given list.
1672 
1673  \param dst Where to store the sprite context.
1674  \param list The primitive list to be used.
1675 */
1677 
1678 /** \brief Fill in a sprite context for a textured sprite.
1679 
1680  This function fills in a pvr_sprite_cxt_t with default parameters
1681  appropriate for rendering a textured sprite in the given list.
1682 
1683  \param dst Where to store the sprite context.
1684  \param list The primitive list to be used.
1685  \param textureformat The format of the texture used.
1686  \param tw The width of the texture, in pixels.
1687  \param th The height of the texture, in pixels.
1688  \param textureaddr A pointer to the texture.
1689  \param filtering The type of filtering to use.
1690 
1691  \see pvr_txr_fmts
1692  \see pvr_filter_modes
1693 */
1695  int textureformat, int tw, int th, pvr_ptr_t textureaddr,
1696  int filtering);
1697 
1698 /** \brief Create a modifier volume header.
1699 
1700  This function fills in a modifier volume header with the parameters
1701  specified. Note that unlike for polygons and sprites, there is no context
1702  step for modifiers.
1703 
1704  \param dst Where to store the modifier header.
1705  \param list The primitive list to be used.
1706  \param mode The mode for this modifier.
1707  \param cull The culling mode to use.
1708 
1709  \see pvr_mod_modes
1710  \see pvr_cull_modes
1711 */
1712 void pvr_mod_compile(pvr_mod_hdr_t *dst, pvr_list_t list, uint32 mode,
1713  uint32 cull);
1714 
1715 /** \brief Compile a polygon context into a polygon header that is affected by
1716  modifier volumes.
1717 
1718  This function works pretty similarly to pvr_poly_compile(), but compiles
1719  into the header type that is affected by a modifier volume. The context
1720  should have been created with either pvr_poly_cxt_col_mod() or
1721  pvr_poly_cxt_txr_mod().
1722 
1723  \param dst Where to store the compiled header.
1724  \param src The context to compile.
1725 */
1727 
1728 /** \brief Fill in a polygon context for non-textured polygons affected by a
1729  modifier volume.
1730 
1731  This function fills in a pvr_poly_cxt_t with default parameters appropriate
1732  for rendering a non-textured polygon in the given list that will be affected
1733  by modifier volumes.
1734 
1735  \param dst Where to store the polygon context.
1736  \param list The primitive list to be used.
1737 */
1739 
1740 /** \brief Fill in a polygon context for a textured polygon affected by
1741  modifier volumes.
1742 
1743  This function fills in a pvr_poly_cxt_t with default parameters appropriate
1744  for rendering a textured polygon in the given list and being affected by
1745  modifier volumes.
1746 
1747  \param dst Where to store the polygon context.
1748  \param list The primitive list to be used.
1749  \param textureformat The format of the texture used (outside).
1750  \param tw The width of the texture, in pixels (outside).
1751  \param th The height of the texture, in pixels (outside).
1752  \param textureaddr A pointer to the texture (outside).
1753  \param filtering The type of filtering to use (outside).
1754  \param textureformat2 The format of the texture used (inside).
1755  \param tw2 The width of the texture, in pixels (inside).
1756  \param th2 The height of the texture, in pixels (inside).
1757  \param textureaddr2 A pointer to the texture (inside).
1758  \param filtering2 The type of filtering to use (inside).
1759 
1760  \see pvr_txr_fmts
1761  \see pvr_filter_modes
1762 */
1764  int textureformat, int tw, int th,
1765  pvr_ptr_t textureaddr, int filtering,
1766  int textureformat2, int tw2, int th2,
1767  pvr_ptr_t textureaddr2, int filtering2);
1768 
1769 /* Texture handling **************************************************/
1770 
1771 /* Helper functions for handling texture tasks of various kinds. */
1772 
1773 /** \brief Load raw texture data from an SH-4 buffer into PVR RAM.
1774 
1775  This essentially just acts as a memcpy() from main RAM to PVR RAM, using
1776  the store queues.
1777 
1778  \param src The location in main RAM holding the texture.
1779  \param dst The location in PVR RAM to copy to.
1780  \param count The size of the texture in bytes (must be a multiple
1781  of 32).
1782 */
1783 void pvr_txr_load(void * src, pvr_ptr_t dst, uint32 count);
1784 
1785 /** \defgroup pvr_txrload_constants Texture loading constants
1786 
1787  These are constants for the flags parameter to pvr_txr_load_ex() or
1788  pvr_txr_load_kimg().
1789 
1790  @{
1791 */
1792 #define PVR_TXRLOAD_4BPP 0x01 /**< \brief 4BPP format */
1793 #define PVR_TXRLOAD_8BPP 0x02 /**< \brief 8BPP format */
1794 #define PVR_TXRLOAD_16BPP 0x03 /**< \brief 16BPP format */
1795 #define PVR_TXRLOAD_FMT_MASK 0x0f /**< \brief Bits used for basic formats */
1796 
1797 #define PVR_TXRLOAD_VQ_LOAD 0x10 /**< \brief Do VQ encoding (not supported yet, if ever) */
1798 #define PVR_TXRLOAD_INVERT_Y 0x20 /**< \brief Invert the Y axis while loading */
1799 #define PVR_TXRLOAD_FMT_VQ 0x40 /**< \brief Texture is already VQ encoded */
1800 #define PVR_TXRLOAD_FMT_TWIDDLED 0x80 /**< \brief Texture is already twiddled */
1801 #define PVR_TXRLOAD_FMT_NOTWIDDLE 0x80 /**< \brief Don't twiddle the texture while loading */
1802 #define PVR_TXRLOAD_DMA 0x8000 /**< \brief Use DMA to load the texture */
1803 #define PVR_TXRLOAD_NONBLOCK 0x4000 /**< \brief Use non-blocking loads (only for DMA) */
1804 #define PVR_TXRLOAD_SQ 0x2000 /**< \brief Use store queues to load */
1805 /** @} */
1806 
1807 /** \brief Load texture data from an SH-4 buffer into PVR RAM, twiddling it in
1808  the process.
1809 
1810  This function loads a texture to the PVR's RAM with the specified set of
1811  flags. It will currently always twiddle the data, whether you ask it to or
1812  not, and many of the parameters are just plain not supported at all...
1813  Pretty much the only supported flag, other than the format ones is the
1814  PVR_TXRLOAD_INVERT_Y one.
1815 
1816  This will be slower than using pvr_txr_load() in pretty much all cases, so
1817  unless you need to twiddle your texture, just use that instead.
1818 
1819  \param src The location to copy from.
1820  \param dst The location to copy to.
1821  \param w The width of the texture, in pixels.
1822  \param h The height of the texture, in pixels.
1823  \param flags Some set of flags, ORed together.
1824 
1825  \see pvr_txrload_constants
1826 */
1827 void pvr_txr_load_ex(void * src, pvr_ptr_t dst, uint32 w, uint32 h, uint32 flags);
1828 
1829 /** \brief Load a KOS Platform Independent Image (subject to constraint
1830  checking).
1831 
1832  This function loads a KOS Platform Independent image to the PVR's RAM with
1833  the specified set of flags. This function, unlike pvr_txr_load_ex() supports
1834  everything in the flags available, other than what's explicitly marked as
1835  not supported.
1836 
1837  \param img The image to load.
1838  \param dst The location to copy to.
1839  \param flags Some set of flags, ORed together.
1840 
1841  \see pvr_txrload_constants
1842 */
1843 void pvr_txr_load_kimg(kos_img_t *img, pvr_ptr_t dst, uint32 flags);
1844 
1845 
1846 /* PVR DMA ***********************************************************/
1847 
1848 /** \brief PVR DMA interrupt callback type.
1849 
1850  Functions that act as callbacks when DMA completes should be of this type.
1851  These functions will be called inside an interrupt context, so don't try to
1852  use anything that might stall.
1853 
1854  \param data User data passed in to the pvr_dma_transfer()
1855  function.
1856 */
1857 typedef void (*pvr_dma_callback_t)(ptr_t data);
1858 
1859 /** \brief Perform a DMA transfer to the PVR.
1860 
1861  This function copies a block of data to the PVR or its memory via DMA. There
1862  are all kinds of constraints that must be fulfilled to actually do this, so
1863  make sure to read all the fine print with the parameter list.
1864 
1865  If a callback is specified, it will be called in an interrupt context, so
1866  keep that in mind in writing the callback.
1867 
1868  \param src Where to copy from. Must be 32-byte aligned.
1869  \param dest Where to copy to. Must be 32-byte aligned.
1870  \param count The number of bytes to copy. Must be a multiple of
1871  32.
1872  \param type The type of DMA transfer to do (see list of modes).
1873  \param block Non-zero if you want the function to block until the
1874  DMA completes.
1875  \param callback A function to call upon completion of the DMA.
1876  \param cbdata Data to pass to the callback function.
1877  \retval 0 On success.
1878  \retval -1 On failure. Sets errno as appropriate.
1879 
1880  \par Error Conditions:
1881  \em EINPROGRESS - DMA already in progress \n
1882  \em EFAULT - dest is not 32-byte aligned \n
1883  \em EIO - I/O error
1884 
1885  \see pvr_dma_modes
1886 */
1887 int pvr_dma_transfer(void * src, uint32 dest, uint32 count, int type,
1888  int block, pvr_dma_callback_t callback, ptr_t cbdata);
1889 
1890 /** \defgroup pvr_dma_modes Transfer modes with PVR DMA
1891  @{
1892 */
1893 #define PVR_DMA_VRAM64 0 /**< \brief Transfer to VRAM in interleaved mode */
1894 #define PVR_DMA_VRAM32 1 /**< \brief Transfer to VRAM in linear mode */
1895 #define PVR_DMA_TA 2 /**< \brief Transfer to the tile accelerator */
1896 /** @} */
1897 
1898 /** \brief Load a texture using PVR DMA.
1899 
1900  This is essentially a convenience wrapper for pvr_dma_transfer(), so all
1901  notes that apply to it also apply here.
1902 
1903  \param src Where to copy from. Must be 32-byte aligned.
1904  \param dest Where to copy to. Must be 32-byte aligned.
1905  \param count The number of bytes to copy. Must be a multiple of
1906  32.
1907  \param block Non-zero if you want the function to block until the
1908  DMA completes.
1909  \param callback A function to call upon completion of the DMA.
1910  \param cbdata Data to pass to the callback function.
1911  \retval 0 On success.
1912  \retval -1 On failure. Sets errno as appropriate.
1913 
1914  \par Error Conditions:
1915  \em EINPROGRESS - DMA already in progress \n
1916  \em EFAULT - dest is not 32-byte aligned \n
1917  \em EIO - I/O error
1918 */
1919 int pvr_txr_load_dma(void * src, pvr_ptr_t dest, uint32 count, int block,
1920  pvr_dma_callback_t callback, ptr_t cbdata);
1921 
1922 /** \brief Load vertex data to the TA using PVR DMA.
1923 
1924  This is essentially a convenience wrapper for pvr_dma_transfer(), so all
1925  notes that apply to it also apply here.
1926 
1927  \param src Where to copy from. Must be 32-byte aligned.
1928  \param count The number of bytes to copy. Must be a multiple of
1929  32.
1930  \param block Non-zero if you want the function to block until the
1931  DMA completes.
1932  \param callback A function to call upon completion of the DMA.
1933  \param cbdata Data to pass to the callback function.
1934  \retval 0 On success.
1935  \retval -1 On failure. Sets errno as appropriate.
1936 
1937  \par Error Conditions:
1938  \em EINPROGRESS - DMA already in progress \n
1939  \em EFAULT - dest is not 32-byte aligned \n
1940  \em EIO - I/O error
1941  */
1942 int pvr_dma_load_ta(void * src, uint32 count, int block,
1943  pvr_dma_callback_t callback, ptr_t cbdata);
1944 
1945 /** \brief Is PVR DMA is inactive?
1946  \return Non-zero if there is no PVR DMA active, thus a DMA
1947  can begin or 0 if there is an active DMA.
1948 */
1949 int pvr_dma_ready();
1950 
1951 /** \brief Initialize PVR DMA. */
1952 void pvr_dma_init();
1953 
1954 /** \brief Shut down PVR DMA. */
1955 void pvr_dma_shutdown();
1956 
1957 /*********************************************************************/
1958 
1959 
1960 __END_DECLS
1961 
1962 #endif
1963