dreamcast.wiki - User contributions [en]

Twiddling

2025-07-18T12:53:49Z

Cooljerk:

== General Idea ==
How to generated the twiddled index from an untwiddled texture:

Original: Twiddled:

0 1 2 3 0 2 8 A
4 5 6 7 1 3 9 B
8 9 A B 4 6 C E
C D E F 5 7 D F
G H I J G I O Q
K L M N H J P R
O P Q R K M S U
S T U V L N T V
W X Y Z W Y % &
~ ! # $ X Z ^ *
% ^ & * ~ # ( _
( ) _ + ! $ ) +

The matching characters between the two images represent the same pixel, just relocated. These images would be 4 * 12 pixel images, but the steps work for any valid '''2^x * 2^'''y sizes, where x and y are whole numbers.

Now lets say we want to find the twiddled index of the untwiddled '''"O"''' pixel (index 24). By hand we can work it out and tell the twiddle index should be "18", but what algorithm/logic can we use to find this automatically for any '''i'''?

Here are my steps:
* We first need to start by figuring out the "Biggest-Order Inverted-N" ('''BOIN''') that fits in this image.
* Now if our starting image was a square, then the BOIN is the same size as the image
* For rectangles like this, we have to find the smallest side first (width) then our BOIN is width * width
* If we start off with a rectangle, then we need to do an extra step that squares can skip.
* Notice how we can completely encapsulate the whole image with '''(bigger_side / smaller_side) == 3''' BOINs? Our first step is to determine which of these BOINs our index '''i''' belongs in.
* We can take advantage of a quirk I mentioned earlier. Notice how the first BOIN contains the first 1/3 of the original pixels, the 2nd BOIN contains the next 1/3 and the 3rd BOIN contains the last 1/3.
* Therefore using the formula '''k = floor(i / (BOIN area == 4 * 4 = 16)) == 1''' we can determine that our twiddled index is somewhere in the middle/2nd BOIN (Since '''k''' is of the set '''{0,1,2}''')
* Note the index where our BOIN starts according to the original texture. The first index in the 2nd BOIN is "16". Keep track of this value, lets call it '''d'''
* Also keep track of the index where our BOIN starts according to the twiddled texture, this is also '''16''' in this case. Lets add this to a running sum '''s'''
* Forget about the other two BOINs and subtract '''d''' from the indexes in our new BOIN as well as '''i'''

So now we have:

i == 8
0 2 8 A
1 3 9 B
4 6 C E
5 7 D F

Great! We can already see by hand that this still looks right, but how do we automatically solve square BOINs?
* In order to solve a square BOIN, we need to determine what quadrant our pixel is in
* So we determine how many pixels are in each quadrant (4 per quadrant here, '''== a'''), Then calculate '''k = floor(i / a) == 2''' to know its in the 3rd quadrant ('''k''' is in the set '''{0,1,2,3}''').
* That means its in the top right. So we need to set '''d = a * k'''), add our new '''s''' value to the running sum, discard the other quadrants, then subtract '''i''' and the new BOIN's indexes by '''d'''
* The easy way to calculate the new part of '''s''' is that:
** top left quadrant is '''0'''
** top right quad is '''BOIN-width / 2'''
** bottom left is '''BOIN-width * (BOIN-height / 2)'''
** bottom right is '''(BOIN-width * (BOIN-height / 2)) + (BOIN-width / 2)'''

Now we have:

i == 0
0 2
1 3

You would repeat until we have a single pixel. Once we have the last pixel, our new twiddled index should be the running sum '''s''' (16 + 2 + 0 == 18)

== DISCLAIMER ==

This theorized solution has only been tested on a few examples by hand, so I might have missed something. But I believe at least the general logic of this is sound. Also note for implementation, some of the divisions could be replaced with bit-shifting since some of those numbers are guaranteed to be powers of 2.

For an example of an algorithm that does the reverse (Convert twiddled index to untwiddled), you can refer to [https://github.com/Protofall/Crayon-Utilities/blob/master/DtexToRGBA8888/DtexToRGBA8888.c#L146 this code made by JamoHTP]

DCWiki:Software

2025-07-18T12:52:39Z

Cooljerk: /* Software */

== Software ==
{| style="width:100%"
! style="width: 50%"|Dreamcast Games and Software
! style="width: 50%"|Development and Technical
|-
| style="padding: 5px;vertical-align:top"|
* Officially [[Licensed games and software|licensed games and software]]
* [[Online Services]]
* Commercially sold, independently developed [[Indie games|indie games]]
* 3rd-party [[Unlicensed software|unlicensed software]]
* [[Freeware homebrew games|Homebrew games and ports]] (freeware)
* [[Emulators on Dreamcast|Emulating other systems]] on your Dreamcast
* [[Media players]]
* [[Hardware Tests]]
* [[Other Dreamcast software]] (utilities and other miscellanea)
* [[VMU games]]
* [[Old tools]]
| style="padding: 5px;vertical-align:top"|
{|
* [[Development]]
** [[Getting Started with Dreamcast development|Get Started]]
** [[Programming language support]]
** [[Engine & Library]]
** [[Tools and Utilities]]
** [https://kos-docs.dreamcast.wiki/ KallistiOS documentation]
** [https://sh4-sim.dreamcast.wiki/ SH4 Pipeline Simulator]
* [[Dreamcast emulators]]
* [[VMU emulators]]
* [[Boot process]]
* [[Memory map]], [[VRAM]]
* [[IP.BIN]], [[MR image]], [[Scrambling]]
* [[BIOS]]
* [[Useful programming tips]]
* [[NetBSD/Dreamcast]]
|}
|}

Development

2025-07-18T12:52:08Z

2025-04-05T14:58:50Z

Cooljerk:

Text Rendering

2025-04-05T14:57:21Z

Cooljerk:

Text Rendering

2025-04-05T14:56:59Z

Cooljerk: Created page with "Now that we can display our font texture with transparency correctly, let’s build our function to render text. To do this, we’ll have to manipulate the UV coordinates of the texture we render with. We start by making a clone of our SubmitQuad function, which we’ll call SubmitText. This will take some different parameters. First, it’ll take a const char* Input string. This is a c-style string, which is just an array of bytes on the stack. We want to take a font c..."

Dreamcast Tutorial

2025-04-05T14:54:55Z

Cooljerk:

While many resources exist to explain individual parts of developing games and applications for the Dreamcast, there are not many comprehensive tutorials that detail the entire process. The following tutorial has been created to more thoroughly explain Dreamcast development topics towards a goal of creating fully featured applications. It is meant to be a full tutorial for beginners, starting from bare text files. This is a table of contents for topics the tutorial covers, in order.

=== First Steps ===
* [[Makefile]]
* [[Main.cpp]]

=== Texturing ===
* [[Adding a Romdisk]]
* [[Drawing a Texture]]
* [[Textures and Meshes]]
* [[Transparent Textures]]

=== Systems ===
* [[Text Rendering]]
* [[Event Handling]]

DCWiki:Software

2025-04-05T14:54:02Z

Cooljerk:

== Software ==
{| style="width:100%"
! style="width: 50%"|Dreamcast Games and Software
! style="width: 50%"|Development and Technical
|-
| style="padding: 5px;vertical-align:top"|
* Officially [[Licensed games and software|licensed games and software]]
* [[Online Services]]
* Commercially sold, independently developed [[Indie games|indie games]]
* 3rd-party [[Unlicensed software|unlicensed software]]
* [[Freeware homebrew games|Homebrew games and ports]] (freeware)
* [[Emulators on Dreamcast|Emulating other systems]] on your Dreamcast
* [[Media players]]
* [[Hardware Tests]]
* [[Other Dreamcast software]] (utilities and other miscellanea)
* [[VMU games]]
* [[Old tools]]
| style="padding: 5px;vertical-align:top"|
{|
* [[Development]]
** [[Getting Started with Dreamcast development|Get Started]]
** [[Programming language support]]
** [[Engine & Library]]
** [[Tools and Utilities]]
** [https://kos-docs.dreamcast.wiki/ KallistiOS documentation]
** [https://sh4-sim.dreamcast.wiki/ SH4 Pipeline Simulator]
** [[Dreamcast Tutorial]]
*** [[Makefile]]
*** [[Main.cpp]]
*** [[Adding a Romdisk]]
*** [[Drawing a Texture]]
*** [[Textures and Meshes]]
*** [[Transparent Textures]]
*** [[Event Handling]]
* [[Dreamcast emulators]]
* [[VMU emulators]]
* [[Boot process]]
* [[Memory map]], [[VRAM]]
* [[IP.BIN]], [[MR image]], [[Scrambling]]
* [[BIOS]]
* [[Useful programming tips]]
* [[NetBSD/Dreamcast]]
|}
|}

Transparent Textures

2025-04-05T14:53:32Z

Cooljerk:

Up till now, we’ve been relying on our attached console to have our dreamcast talk back to us. Now that we can map textures to the screen, let’s use that to create a function that can print text through the Dreamcast. We will learn how to use translucent textures in the process as well.

Our font will take the form of a Texture Atlus. A texture atlus is a giant texture with lots of smaller textures in it. You select which texture you use by changing the UV coordinates of the vertices.

The general idea behind our text rendering code will rely on how ASCII works. Our text will be a c-style string, which is an array of bytes, where each byte is a single character. These bytes map to characters using an agreed-upon code called ASCII. We will take the numeric value of the characters in our C-style string and map them to positions on our font.

Our font will come in two sizes – 16x16 pixel ‘Large’ font, and 8x8 pixel ‘small’ font. We will map all characters A through Z, in caps, plus 0-9, plus the symbols mapped to 0-9, as well as a few punctuation marks and brackets. We will draw the fonts in a row in a png. Calculated out, our font will be 1024 pixels wide, which is the maximum amount the Dreamcast can have. Each font character needs to be at least 16x16 pixels big. I settled on my final font texture size being 1024x128 pixels big. The dimensions of the texture need to be a power of 2. 128 pixels big gives me eight rows of 16 pixel tall cells for font characters, where each row is a different font.

By looking up the ASCII character codes, we can find the order our characters come in. We are mapping 64 characters, from ASCII code 32 to 96.

I have provided a sample font.png, you can use it or make your own. The 8x8 fonts map to the upper left corner of a 16x16 grid cell. When you have your font made, place it in our romdisk folder so we can use it.

Now let’s try drawing our font texture first. In our Texture_manager constructor, let’s have it build our font texture:
/* Setup background.png */
CompileContext("/rd/font.png", font_png, &TempTxr, 1024, 128, PNG_NO_ALPHA, PVR_FILTER_NONE);
Textures[font_png] = TempTxr;

Make sure we add font_png to our TextureEnums.h:
#ifndef TEXTUREENUMS_H
#define TEXTUREENUMS_H
enum TextureEnum {
background_png = 0,
font_png, /* = 1 */
TX_NULL
};
#endif // TEXTUREENUMS_H

Now in our GameState.Render() function, let’s submit a quad to draw with font_png. Our Font texture size is 1024x128:

void GameState::Render()
{
pvr_wait_ready();
RenderDepth = 0;
pvr_scene_begin();
pvr_list_begin(PVR_LIST_OP_POLY);
SubmitQuad(background_png, 0, 0, 640, 480);
SubmitQuad(font_png, 0, 0, 1024, 128);
pvr_list_finish();
pvr_scene_finish();
}

Let’s run it and see if it works. We should see our background with our font texture drawn in front of it. It is much larger than the screen, so it goes to the right. Currently, we are drawing the font with no transparency, let’s change that. To do that, we will need to change our definition in texture_manager constructor:
/* Setup font.png */
CompileContext("/rd/font.png", font_png, font_png, 1024, 128, PNG_FULL_ALPHA, PVR_FILTER_NONE);

We need to edit our font.png texture to have transparent pixels. Open it up in gimp, and create a new layer with a transparent background. Put it below our font.png layer. Select our font.png layer to work in. Now, on the menu bar in gimp, click “select” -> “By Color” and click on the pink color in the font image. Press delete, this will turn the pixels that used to be pink into transparent pixels.

Now, we need to make sure we have 16-bit precision. Click Image-> Precision -> 16 bit integer. Now we need to export our image. Click File -> Export As, and in the dialog box, name it font_transparent.png in our romdisk folder. In the png export dialog, make sure “save color values from transparent pixels” is checked.

We need to add a new value for our new texture in our TextureEnum.h file:

#ifndef TEXTUREENUMS_H
#define TEXTUREENUMS_H
enum TextureEnum {
background_png = 0,
font_png, /* = 1 */
font_transparent_png,
TX_NULL
};
#endif // TEXTUREENUMS_H

Now, we need to make our texture_manager() constructor call our new transparent font texture:

texture_manager::texture_manager()
{
Texture_t TempTxr; /* This is a dummy Texture_t object we
reuse to build out our Texture map */
/* Setup background.png */
CompileContext("/rd/background.png", background_png, 512, 512, PNG_NO_ALPHA, PVR_FILTER_BILINEAR);

/* Setup font.png */
CompileContext("/rd/font.png", font_png, 1024, 128, PNG_FULL_ALPHA, PVR_FILTER_NONE);

/* Setup font_transparent.png */
CompileContext("/rd/font_transparent.png", font_transparent_png, 1024, 128, PNG_FULL_ALPHA, PVR_FILTER_NONE);

}

Since this png has transparent pixels, we change our flag to PNG_FULL_ALPHA. This is a font texture, so we don’t really want any filtering, so we use PVR_FILTER_NONE. PNG_FULL_ALPHA means it needs to be drawn in our Translucent poly bin, currently we only draw in our opaque one. Let’s change it so it draws with the right bin, to do that we need to change our submission code:

void GameState::Render()
{
pvr_wait_ready();
RenderDepth = 0;
pvr_scene_begin();
pvr_list_begin(PVR_LIST_OP_POLY);
SubmitQuad(background_png, 0, 0, 640, 480);
pvr_list_finish();
pvr_list_begin(PVR_LIST_TR_POLY);
SubmitQuad(font_png, 0, 0, 1024, 128);
pvr_list_finish();
pvr_scene_finish();
}
We now have two render lists. We first open our PVR_LIST_OP_POLY bin for Opaque polygons, then submit our quad for the background_png texture. Once we’re done submitting it, we close our PVR_LIST_OP_POLY bin, then open our PVR_LIST_TR_POLY bin list. This list holds vertices for transparent polygons. We need to change our ContextCompile code in our Texture_manager.cpp class to use the right Poly list when compiling the texture header:

void CompileContext(char* Path, TextureEnum TxrID, Texture_t* TempTxr, uint32_t W, uint32_t H, uint32_t PngMode, uint32_t Filtering)
{
TempTxr->Width = W;
TempTxr->Height = H;
TempTxr->TextureID = TxrID;
TempTxr->m_Ptr = pvr_mem_malloc(W * H * 2);
png_to_texture(Path, TempTxr->m_Ptr, PngMode);
/* Set our Texture Type */
uint32_t Texture_Fmt;
pvr_list_t Poly_List;
switch(PngMode)
{
/* Our PNG has 4-bit alpha channel, Translucent */
case PNG_FULL_ALPHA:
{
Texture_Fmt = PVR_TXRFMT_ARGB4444;
Poly_List = PVR_LIST_TR_POLY;
}
break;
/* Our PNG has 1-bit alpha channel, Punch-thru */
case PNG_MASK_ALPHA:
{
Texture_Fmt = PVR_TXRFMT_ARGB1555;
Poly_List = PVR_LIST_PT_POLY;
}
break;
/* Our PNG has no alpha channel */
default: /* PNG_NO_ALPHA, Opaque */
{
Texture_Fmt = PVR_TXRFMT_RGB565;
Poly_List = PVR_LIST_OP_POLY;
}
break;
}
pvr_poly_cxt_txr(&TempTxr->m_Context, /* Dest Context to write to */
Poly_List, /* Polygon Bin Type */
Texture_Fmt, /* Texture Format */
W, /* Texture Width */
H, /* Texture Height */
TempTxr->m_Ptr, /* Texture Pointer */
Filtering); /* Filtering */
pvr_poly_compile(&TempTxr->m_Header, &TempTxr→m_Context);
Textures[TxrID] = TempTxr;
}

We use a variable called Poly_list of type pvr_list_t. We set it to PVR_LIST_TR_POLY if we have PNG_FULL_ALPHA using PVR_TXRFMT_ARGB4444. We use PVR_LIST_PT_POLY if we have PNG_MASK_ALPHA using PVR_TXRFMT_ARGB1555. We use PVR_LIST_OP_POLY if we have PNG_NO_ALPHA using PVR_TXR_FMT_RGB565. We substitute this variable in our pvr_poly_cxt_txr function. Now, when we render our font texture, our transparent pixels will actually be transparent.

Let’s add a guard so our Render() function won’t draw a mesh with vertices in the wrong list, just in case. In our gamestate.h header file, let’s add a new private variable called OpenPolyList of type pvr_list_t:

private:
cont_state_t PrevControllerState;
texture_manager m_Textures;
void SubmitPolygon(TextureEnum Tex_In, MeshEnum Mesh_In);
void SubmitQuad(TextureEnum Tex_In, uint32_t X_In, uint32_t Y_In, uint32_t W_In, uint32_t H_In);
mesh_manager m_Meshes;
pvr_list_t OpenPolyList;
};
#endif // GAMESTATE_H

This variable will hold a state indicating when PVR poly bin we are submitting to. Let’s change our Render code to indicate this:

void GameState::Render()
{
pvr_wait_ready();
RenderDepth = 0;
pvr_scene_begin();

/* Opaque Polygons */
pvr_list_begin(PVR_LIST_OP_POLY);
OpenPolyList = PVR_LIST_OP_POLY
SubmitQuad(background_png, 0, 0, 640, 480);
OpenPolyList = 0;
pvr_list_finish();

/* Translucent Polygons */
pvr_list_begin(PVR_LIST_TR_POLY);
OpenPolyList = PVR_LIST_TR_POLY
SubmitQuad(font_png, 0, 0, 1024, 128);
OpenPolyList = 0;
pvr_list_finish();

pvr_scene_finish();
}

Now, when we open a list, it’ll set OpenPolyList, and when we close it, we’ll clear it with 0. Our SubmitQuad function can now check if the OpenPolyList matches the Context in our Texture:

void GameState::SubmitQuad(TextureEnum Tex_In, uint32_t X_In, uint32_t Y_In, uint32_t W_In, uint32_t H_In)
{
if(OpenPolyList == m_Textures.GetTexture(Tex_In)->m_Context.list_type)
{
/* Texture Mapping */
Texture_t* Texture = m_Textures.GetTexture(Tex_In);
pvr_prim(&Texture->m_Header, sizeof(Texture->m_Header));
/* Vertex Submission */
pvr_vertex_t T_vertex;
pvr_vertex_t* Vertex_ptr;
for(int i = 0; i < m_Meshes.Get(e_Quad)->m_VtxCount; i++)
{
/* Get the vertex */
Vertex_ptr = m_Meshes.Get(e_Quad)->GetVertex(i);
/* Map all the information */
T_vertex.flags = Vertex_ptr->flags;
T_vertex.x = X_In + (Vertex_ptr->x * W_In);
T_vertex.y = Y_In + (Vertex_ptr->y * H_In);
T_vertex.z = Vertex_ptr->z + RenderDepth;
T_vertex.u = Vertex_ptr->u;
T_vertex.v = Vertex_ptr->v;
T_vertex.argb = Vertex_ptr->argb;
T_vertex.oargb = Vertex_ptr->oargb;
/* Submit data */
pvr_prim(&T_vertex, sizeof(T_vertex));
}
RenderDepth += 0.1;
}
}

Our Texture now won’t draw if it’s in the wrong bin. Let’s test this by intentionally putting our font texture in the opaque bin despite it being a transparent texture:

void GameState::Render()
{
pvr_wait_ready();
RenderDepth = 0;
pvr_scene_begin();

/* Opaque Polygons */
pvr_list_begin(PVR_LIST_OP_POLY);
OpenPolyList = PVR_LIST_OP_POLY
SubmitQuad(background_png, 0, 0, 640, 480);
SubmitQuad(font_png, 0, 0, 1024, 128);
OpenPolyList = 0;
pvr_list_finish();

/* Translucent Polygons */
pvr_list_begin(PVR_LIST_TR_POLY);
OpenPolyList = PVR_LIST_TR_POLY
//SubmitQuad(font_png, 0, 0, 1024, 128);
OpenPolyList = 0;
pvr_list_finish();

pvr_scene_finish();
}
If we do this, then our font_png quad won’t render, and our console will output an error message letting us know. Let’s create a second font texture, this time fully transparent. In our texture_manager constructor:

texture_manager::texture_manager()
{
Texture_t TempTxr; /* This is a dummy Texture_t object we
reuse to build out our Texture map */
/* Setup background.png */
CompileContext("/rd/background.png", background_png, 512, 512, PNG_NO_ALPHA, PVR_FILTER_BILINEAR);

/* Setup font.png */
CompileContext("/rd/font.png", font_png, 1024, 128, PNG_FULL_ALPHA, PVR_FILTER_NONE);

/* Setup font_transparent.png */
CompileContext("/rd/font_transparent.png", font_transparent_png, 1024, 128, PNG_FULL_ALPHA, PVR_FILTER_NONE);

}

make sure we have a TextureEnum for font_transparent_png:

#ifndef TEXTUREENUMS_H
#define TEXTUREENUMS_H
enum TextureEnum {
background_png = 0,
font_png, /* = 1 */
font_transparent_png,
TX_NULL
};
const char* GetTextureEnumString(TextureEnum In)
{
std::string TxEnum;
switch(In)
{
case background_png : TxEnum = "background_png";
break;
case font_png: TxEnum = "font_png";
break;
case font_transparent_png : TxEnum = "font_transparent_png";
break;
}
return TxEnum.c_str();
}
#endif // TEXTUREENUMS_H
Let’s have SubmitQuads print out an error if we submit a vertex to the wrong bin list. We want it to be able to tell us which texture we called that was incompatible, along with the format of the texture and the OpenPolyList we are working on. We already have a function to turn our TextureEnums into a string, let’s create a quick function to turn our PolyBinList into a string. In TextureEnums.h, add:

#ifdef TEXTUREENUMS_CPP
const char* GetTextureString(TextureEnum In)
{
std::string TxEnum;
switch(In)
{
case background_png : TxEnum = "background_png";
break;
case font_png: TxEnum = "font_png";
break;
case font_transparent_png : TxEnum = "font_transparent_png";
break;
}
return TxEnum.c_str();
}
const char* GetPolyBinString(pvr_list_t Input)
{
std::string TxFmt;
switch(Input)
{
case PVR_LIST_OP_MOD : TxFmt = "Opaque Modifier";
break;
case PVR_LIST_TR_POLY: TxFmt = "Transparent";
break;
case PVR_LIST_TR_MOD : TxFmt = "Transparent Modifier";
break;
case PVR_LIST_PT_POLY: TxFmt = "Punch-Thru";
break;
case PVR_LIST_OP_POLY: TxFmt = "Opaque";
break;
}
return TxFmt.c_str();
}
#else
extern const char* GetTextureString(TextureEnum In);
extern const char* GetPolyBinString(pvr_list_t Input);
#endif

We now have a function called GetPolyBinString which can turn a pvr_list_t into a string to print out. Now, let’s create a string to print out our error in our submitquad function. We need to store a flag in our Texture file to let us know if the error has been printed once before, otherwise our error will print out every loop when we render. We’ll call this Warning in our texture_t struct in texture.h:

#ifndef TEXTURE_H
#define TEXTURE_H
#include "kos.h"
#include "stdint.h"
#include "TextureEnums.h"
typedef struct _Texture_t
{
pvr_ptr_t m_Ptr; /* Pointer to VRAM */
pvr_poly_cxt_t m_Context; /* Texture Context settings */
pvr_poly_hdr_t m_Header; /* Texture PVR Header */
uint32_t Width; /* Texture Width */
uint32_t Height; /* Texture Height */
TextureEnum TextureID;
uint8_t RenderWarning; /* Flag letting us know if an error msg has printed once */
} Texture_t;
#endif // TEXTUREENUMS_H

Now let’s set it so our Texture_t has a warning of 0 when created in our Texture_manager compilerContext function:

void texture_manager::CompileContext(char* Path, TextureEnum TxrID, uint32_t W, uint32_t H, uint32_t PngMode, uint32_t Filtering)
{
Texture_t TempTxr; /* This is a dummy Texture_t object we
reuse to build out our Texture map */
TempTxr.RenderWarning = 0;

Now, when we print our error when Rendering, we check if RenderWarning is 0 or not, and set it after printing the error, add this in our gamestate::SubmitQuad function:

else
{
if(m_Textures.GetTexture(Tex_In)->RenderWarning == 0)
{
std::string Txr = GetPolyBinType(m_Textures.GetTexture(Tex_In)->m_Context.list_type);
std::string Ply = GetPolyBinType(OpenPolyList);
std::string TxrID = GetTextureEnumString(m_Textures.GetTexture(Tex_In)->TextureID);
printf("Could not render %s, incorrect Texture Format for this Polygon Bin. Format: %s, Bin: %s\n", TxrID.c_str(), Txr.c_str(), Ply.c_str());
m_Textures.GetTexture(Tex_In)->RenderWarning++;
}
}
}

Now let’s modify the SubmitQuad function in gamestate.cpp:

else
{
if(m_Textures.GetTexture(Tex_In)->RenderWarning == 0)
{
std::string Txr = GetPolyBinString(m_Textures.GetTexture(Tex_In)->m_Context.list_type);
std::string Ply = GetPolyBinString(OpenPolyList);
std::string TxrID = GetTextureString(m_Textures.GetTexture(Tex_In)->TextureID);
printf("Could not render %s, incorrect Texture Format for this Polygon Bin. Format: %s, Bin: %s\n", TxrID.c_str(), Txr.c_str(), Ply.c_str());
m_Textures.GetTexture(Tex_In)->RenderWarning++;
}

Run our program, and we should see an error message telling us we used the wrong texture in the wrong list.

Transparent Textures

2025-04-05T14:50:40Z

Cooljerk: Created page with " font. We will map all characters A through Z, in caps, plus 0-9, plus the symbols mapped to 0-9, as well as a few punctuation marks and brackets. We will draw the fonts in a row in a png. Calculated out, our font will be 1024 pixels wide, which is the maximum amount the Dreamcast can have. Each font character needs to be at least 16x16 pixels big. I settled on my final font texture size being 1024x128 pixels big. The dimensions of the texture need to be a power of 2. 12..."

font. We will map all characters A through Z, in caps, plus 0-9, plus the symbols mapped to 0-9, as well as a few punctuation marks and brackets. We will draw the fonts in a row in a png. Calculated out, our font will be 1024 pixels wide, which is the maximum amount the Dreamcast can have. Each font character needs to be at least 16x16 pixels big. I settled on my final font texture size being 1024x128 pixels big. The dimensions of the texture need to be a power of 2. 128 pixels big gives me eight rows of 16 pixel tall cells for font characters, where each row is a different font.

By looking up the ASCII character codes, we can find the order our characters come in. We are mapping 64 characters, from ASCII code 32 to 96.

I have provided a sample font.png, you can use it or make your own. The 8x8 fonts map to the upper left corner of a 16x16 grid cell. When you have your font made, place it in our romdisk folder so we can use it.

Now let’s try drawing our font texture first. In our Texture_manager constructor, let’s have it build our font texture:
/* Setup background.png */
CompileContext("/rd/font.png", font_png, &TempTxr, 1024, 128, PNG_NO_ALPHA, PVR_FILTER_NONE);
Textures[font_png] = TempTxr;

Make sure we add font_png to our TextureEnums.h:
#ifndef TEXTUREENUMS_H
#define TEXTUREENUMS_H
enum TextureEnum {
background_png = 0,
font_png, /* = 1 */
TX_NULL
};
#endif // TEXTUREENUMS_H

Now in our GameState.Render() function, let’s submit a quad to draw with font_png. Our Font texture size is 1024x128:

void GameState::Render()
{
pvr_wait_ready();
RenderDepth = 0;
pvr_scene_begin();
pvr_list_begin(PVR_LIST_OP_POLY);
SubmitQuad(background_png, 0, 0, 640, 480);
SubmitQuad(font_png, 0, 0, 1024, 128);
pvr_list_finish();
pvr_scene_finish();
}

Let’s run it and see if it works. We should see our background with our font texture drawn in front of it. It is much larger than the screen, so it goes to the right. Currently, we are drawing the font with no transparency, let’s change that. To do that, we will need to change our definition in texture_manager constructor:
/* Setup font.png */
CompileContext("/rd/font.png", font_png, font_png, 1024, 128, PNG_FULL_ALPHA, PVR_FILTER_NONE);

We need to edit our font.png texture to have transparent pixels. Open it up in gimp, and create a new layer with a transparent background. Put it below our font.png layer. Select our font.png layer to work in. Now, on the menu bar in gimp, click “select” -> “By Color” and click on the pink color in the font image. Press delete, this will turn the pixels that used to be pink into transparent pixels.

Now, we need to make sure we have 16-bit precision. Click Image-> Precision -> 16 bit integer. Now we need to export our image. Click File -> Export As, and in the dialog box, name it font_transparent.png in our romdisk folder. In the png export dialog, make sure “save color values from transparent pixels” is checked.

We need to add a new value for our new texture in our TextureEnum.h file:

#ifndef TEXTUREENUMS_H
#define TEXTUREENUMS_H
enum TextureEnum {
background_png = 0,
font_png, /* = 1 */
font_transparent_png,
TX_NULL
};
#endif // TEXTUREENUMS_H

Now, we need to make our texture_manager() constructor call our new transparent font texture:

texture_manager::texture_manager()
{
Texture_t TempTxr; /* This is a dummy Texture_t object we
reuse to build out our Texture map */
/* Setup background.png */
CompileContext("/rd/background.png", background_png, 512, 512, PNG_NO_ALPHA, PVR_FILTER_BILINEAR);

/* Setup font.png */
CompileContext("/rd/font.png", font_png, 1024, 128, PNG_FULL_ALPHA, PVR_FILTER_NONE);

/* Setup font_transparent.png */
CompileContext("/rd/font_transparent.png", font_transparent_png, 1024, 128, PNG_FULL_ALPHA, PVR_FILTER_NONE);

}

Since this png has transparent pixels, we change our flag to PNG_FULL_ALPHA. This is a font texture, so we don’t really want any filtering, so we use PVR_FILTER_NONE. PNG_FULL_ALPHA means it needs to be drawn in our Translucent poly bin, currently we only draw in our opaque one. Let’s change it so it draws with the right bin, to do that we need to change our submission code:

void GameState::Render()
{
pvr_wait_ready();
RenderDepth = 0;
pvr_scene_begin();
pvr_list_begin(PVR_LIST_OP_POLY);
SubmitQuad(background_png, 0, 0, 640, 480);
pvr_list_finish();
pvr_list_begin(PVR_LIST_TR_POLY);
SubmitQuad(font_png, 0, 0, 1024, 128);
pvr_list_finish();
pvr_scene_finish();
}
We now have two render lists. We first open our PVR_LIST_OP_POLY bin for Opaque polygons, then submit our quad for the background_png texture. Once we’re done submitting it, we close our PVR_LIST_OP_POLY bin, then open our PVR_LIST_TR_POLY bin list. This list holds vertices for transparent polygons. We need to change our ContextCompile code in our Texture_manager.cpp class to use the right Poly list when compiling the texture header:

void CompileContext(char* Path, TextureEnum TxrID, Texture_t* TempTxr, uint32_t W, uint32_t H, uint32_t PngMode, uint32_t Filtering)
{
TempTxr->Width = W;
TempTxr->Height = H;
TempTxr->TextureID = TxrID;
TempTxr->m_Ptr = pvr_mem_malloc(W * H * 2);
png_to_texture(Path, TempTxr->m_Ptr, PngMode);
/* Set our Texture Type */
uint32_t Texture_Fmt;
pvr_list_t Poly_List;
switch(PngMode)
{
/* Our PNG has 4-bit alpha channel, Translucent */
case PNG_FULL_ALPHA:
{
Texture_Fmt = PVR_TXRFMT_ARGB4444;
Poly_List = PVR_LIST_TR_POLY;
}
break;
/* Our PNG has 1-bit alpha channel, Punch-thru */
case PNG_MASK_ALPHA:
{
Texture_Fmt = PVR_TXRFMT_ARGB1555;
Poly_List = PVR_LIST_PT_POLY;
}
break;
/* Our PNG has no alpha channel */
default: /* PNG_NO_ALPHA, Opaque */
{
Texture_Fmt = PVR_TXRFMT_RGB565;
Poly_List = PVR_LIST_OP_POLY;
}
break;
}
pvr_poly_cxt_txr(&TempTxr->m_Context, /* Dest Context to write to */
Poly_List, /* Polygon Bin Type */
Texture_Fmt, /* Texture Format */
W, /* Texture Width */
H, /* Texture Height */
TempTxr->m_Ptr, /* Texture Pointer */
Filtering); /* Filtering */
pvr_poly_compile(&TempTxr->m_Header, &TempTxr→m_Context);
Textures[TxrID] = TempTxr;
}

We use a variable called Poly_list of type pvr_list_t. We set it to PVR_LIST_TR_POLY if we have PNG_FULL_ALPHA using PVR_TXRFMT_ARGB4444. We use PVR_LIST_PT_POLY if we have PNG_MASK_ALPHA using PVR_TXRFMT_ARGB1555. We use PVR_LIST_OP_POLY if we have PNG_NO_ALPHA using PVR_TXR_FMT_RGB565. We substitute this variable in our pvr_poly_cxt_txr function. Now, when we render our font texture, our transparent pixels will actually be transparent.

Let’s add a guard so our Render() function won’t draw a mesh with vertices in the wrong list, just in case. In our gamestate.h header file, let’s add a new private variable called OpenPolyList of type pvr_list_t:

private:
cont_state_t PrevControllerState;
texture_manager m_Textures;
void SubmitPolygon(TextureEnum Tex_In, MeshEnum Mesh_In);
void SubmitQuad(TextureEnum Tex_In, uint32_t X_In, uint32_t Y_In, uint32_t W_In, uint32_t H_In);
mesh_manager m_Meshes;
pvr_list_t OpenPolyList;
};
#endif // GAMESTATE_H

This variable will hold a state indicating when PVR poly bin we are submitting to. Let’s change our Render code to indicate this:

void GameState::Render()
{
pvr_wait_ready();
RenderDepth = 0;
pvr_scene_begin();

/* Opaque Polygons */
pvr_list_begin(PVR_LIST_OP_POLY);
OpenPolyList = PVR_LIST_OP_POLY
SubmitQuad(background_png, 0, 0, 640, 480);
OpenPolyList = 0;
pvr_list_finish();

/* Translucent Polygons */
pvr_list_begin(PVR_LIST_TR_POLY);
OpenPolyList = PVR_LIST_TR_POLY
SubmitQuad(font_png, 0, 0, 1024, 128);
OpenPolyList = 0;
pvr_list_finish();

pvr_scene_finish();
}

Now, when we open a list, it’ll set OpenPolyList, and when we close it, we’ll clear it with 0. Our SubmitQuad function can now check if the OpenPolyList matches the Context in our Texture:

void GameState::SubmitQuad(TextureEnum Tex_In, uint32_t X_In, uint32_t Y_In, uint32_t W_In, uint32_t H_In)
{
if(OpenPolyList == m_Textures.GetTexture(Tex_In)->m_Context.list_type)
{
/* Texture Mapping */
Texture_t* Texture = m_Textures.GetTexture(Tex_In);
pvr_prim(&Texture->m_Header, sizeof(Texture->m_Header));
/* Vertex Submission */
pvr_vertex_t T_vertex;
pvr_vertex_t* Vertex_ptr;
for(int i = 0; i < m_Meshes.Get(e_Quad)->m_VtxCount; i++)
{
/* Get the vertex */
Vertex_ptr = m_Meshes.Get(e_Quad)->GetVertex(i);
/* Map all the information */
T_vertex.flags = Vertex_ptr->flags;
T_vertex.x = X_In + (Vertex_ptr->x * W_In);
T_vertex.y = Y_In + (Vertex_ptr->y * H_In);
T_vertex.z = Vertex_ptr->z + RenderDepth;
T_vertex.u = Vertex_ptr->u;
T_vertex.v = Vertex_ptr->v;
T_vertex.argb = Vertex_ptr->argb;
T_vertex.oargb = Vertex_ptr->oargb;
/* Submit data */
pvr_prim(&T_vertex, sizeof(T_vertex));
}
RenderDepth += 0.1;
}
}

Our Texture now won’t draw if it’s in the wrong bin. Let’s test this by intentionally putting our font texture in the opaque bin despite it being a transparent texture:

void GameState::Render()
{
pvr_wait_ready();
RenderDepth = 0;
pvr_scene_begin();

/* Opaque Polygons */
pvr_list_begin(PVR_LIST_OP_POLY);
OpenPolyList = PVR_LIST_OP_POLY
SubmitQuad(background_png, 0, 0, 640, 480);
SubmitQuad(font_png, 0, 0, 1024, 128);
OpenPolyList = 0;
pvr_list_finish();

/* Translucent Polygons */
pvr_list_begin(PVR_LIST_TR_POLY);
OpenPolyList = PVR_LIST_TR_POLY
//SubmitQuad(font_png, 0, 0, 1024, 128);
OpenPolyList = 0;
pvr_list_finish();

pvr_scene_finish();
}
If we do this, then our font_png quad won’t render, and our console will output an error message letting us know. Let’s create a second font texture, this time fully transparent. In our texture_manager constructor:

texture_manager::texture_manager()
{
Texture_t TempTxr; /* This is a dummy Texture_t object we
reuse to build out our Texture map */
/* Setup background.png */
CompileContext("/rd/background.png", background_png, 512, 512, PNG_NO_ALPHA, PVR_FILTER_BILINEAR);

/* Setup font.png */
CompileContext("/rd/font.png", font_png, 1024, 128, PNG_FULL_ALPHA, PVR_FILTER_NONE);

/* Setup font_transparent.png */
CompileContext("/rd/font_transparent.png", font_transparent_png, 1024, 128, PNG_FULL_ALPHA, PVR_FILTER_NONE);

}

make sure we have a TextureEnum for font_transparent_png:

#ifndef TEXTUREENUMS_H
#define TEXTUREENUMS_H
enum TextureEnum {
background_png = 0,
font_png, /* = 1 */
font_transparent_png,
TX_NULL
};
const char* GetTextureEnumString(TextureEnum In)
{
std::string TxEnum;
switch(In)
{
case background_png : TxEnum = "background_png";
break;
case font_png: TxEnum = "font_png";
break;
case font_transparent_png : TxEnum = "font_transparent_png";
break;
}
return TxEnum.c_str();
}
#endif // TEXTUREENUMS_H
Let’s have SubmitQuads print out an error if we submit a vertex to the wrong bin list. We want it to be able to tell us which texture we called that was incompatible, along with the format of the texture and the OpenPolyList we are working on. We already have a function to turn our TextureEnums into a string, let’s create a quick function to turn our PolyBinList into a string. In TextureEnums.h, add:

#ifdef TEXTUREENUMS_CPP
const char* GetTextureString(TextureEnum In)
{
std::string TxEnum;
switch(In)
{
case background_png : TxEnum = "background_png";
break;
case font_png: TxEnum = "font_png";
break;
case font_transparent_png : TxEnum = "font_transparent_png";
break;
}
return TxEnum.c_str();
}
const char* GetPolyBinString(pvr_list_t Input)
{
std::string TxFmt;
switch(Input)
{
case PVR_LIST_OP_MOD : TxFmt = "Opaque Modifier";
break;
case PVR_LIST_TR_POLY: TxFmt = "Transparent";
break;
case PVR_LIST_TR_MOD : TxFmt = "Transparent Modifier";
break;
case PVR_LIST_PT_POLY: TxFmt = "Punch-Thru";
break;
case PVR_LIST_OP_POLY: TxFmt = "Opaque";
break;
}
return TxFmt.c_str();
}
#else
extern const char* GetTextureString(TextureEnum In);
extern const char* GetPolyBinString(pvr_list_t Input);
#endif

We now have a function called GetPolyBinString which can turn a pvr_list_t into a string to print out. Now, let’s create a string to print out our error in our submitquad function. We need to store a flag in our Texture file to let us know if the error has been printed once before, otherwise our error will print out every loop when we render. We’ll call this Warning in our texture_t struct in texture.h:

#ifndef TEXTURE_H
#define TEXTURE_H
#include "kos.h"
#include "stdint.h"
#include "TextureEnums.h"
typedef struct _Texture_t
{
pvr_ptr_t m_Ptr; /* Pointer to VRAM */
pvr_poly_cxt_t m_Context; /* Texture Context settings */
pvr_poly_hdr_t m_Header; /* Texture PVR Header */
uint32_t Width; /* Texture Width */
uint32_t Height; /* Texture Height */
TextureEnum TextureID;
uint8_t RenderWarning; /* Flag letting us know if an error msg has printed once */
} Texture_t;
#endif // TEXTUREENUMS_H

Now let’s set it so our Texture_t has a warning of 0 when created in our Texture_manager compilerContext function:

void texture_manager::CompileContext(char* Path, TextureEnum TxrID, uint32_t W, uint32_t H, uint32_t PngMode, uint32_t Filtering)
{
Texture_t TempTxr; /* This is a dummy Texture_t object we
reuse to build out our Texture map */
TempTxr.RenderWarning = 0;

Now, when we print our error when Rendering, we check if RenderWarning is 0 or not, and set it after printing the error, add this in our gamestate::SubmitQuad function:

else
{
if(m_Textures.GetTexture(Tex_In)->RenderWarning == 0)
{
std::string Txr = GetPolyBinType(m_Textures.GetTexture(Tex_In)->m_Context.list_type);
std::string Ply = GetPolyBinType(OpenPolyList);
std::string TxrID = GetTextureEnumString(m_Textures.GetTexture(Tex_In)->TextureID);
printf("Could not render %s, incorrect Texture Format for this Polygon Bin. Format: %s, Bin: %s\n", TxrID.c_str(), Txr.c_str(), Ply.c_str());
m_Textures.GetTexture(Tex_In)->RenderWarning++;
}
}
}

Now let’s modify the SubmitQuad function in gamestate.cpp:

else
{
if(m_Textures.GetTexture(Tex_In)->RenderWarning == 0)
{
std::string Txr = GetPolyBinString(m_Textures.GetTexture(Tex_In)->m_Context.list_type);
std::string Ply = GetPolyBinString(OpenPolyList);
std::string TxrID = GetTextureString(m_Textures.GetTexture(Tex_In)->TextureID);
printf("Could not render %s, incorrect Texture Format for this Polygon Bin. Format: %s, Bin: %s\n", TxrID.c_str(), Txr.c_str(), Ply.c_str());
m_Textures.GetTexture(Tex_In)->RenderWarning++;
}

Run our program, and we should see an error message telling us we used the wrong texture in the wrong list.

Dreamcast Tutorial

2025-04-05T14:50:36Z

Cooljerk:

DCWiki:Software

2025-04-05T14:48:25Z

Cooljerk:

== Software ==
{| style="width:100%"
! style="width: 50%"|Dreamcast Games and Software
! style="width: 50%"|Development and Technical
|-
| style="padding: 5px;vertical-align:top"|
* Officially [[Licensed games and software|licensed games and software]]
* [[Online Services]]
* Commercially sold, independently developed [[Indie games|indie games]]
* 3rd-party [[Unlicensed software|unlicensed software]]
* [[Freeware homebrew games|Homebrew games and ports]] (freeware)
* [[Emulators on Dreamcast|Emulating other systems]] on your Dreamcast
* [[Media players]]
* [[Hardware Tests]]
* [[Other Dreamcast software]] (utilities and other miscellanea)
* [[VMU games]]
* [[Old tools]]
| style="padding: 5px;vertical-align:top"|
{|
* [[Development]]
** [[Getting Started with Dreamcast development|Get Started]]
** [[Programming language support]]
** [[Engine & Library]]
** [[Tools and Utilities]]
** [https://kos-docs.dreamcast.wiki/ KallistiOS documentation]
** [https://sh4-sim.dreamcast.wiki/ SH4 Pipeline Simulator]
** [[Dreamcast Tutorial]]
*** [[Makefile]]
*** [[Main.cpp]]
*** [[Adding a Romdisk]]
*** [[Drawing a Texture]]
*** [[Textures and Meshes]]
*** [[Event Handling]]
* [[Dreamcast emulators]]
* [[VMU emulators]]
* [[Boot process]]
* [[Memory map]], [[VRAM]]
* [[IP.BIN]], [[MR image]], [[Scrambling]]
* [[BIOS]]
* [[Useful programming tips]]
* [[NetBSD/Dreamcast]]
|}
|}

2025-04-05T14:25:33Z

Cooljerk:

Drawing a Texture

2025-04-05T14:24:50Z

Cooljerk:

Drawing a Texture

2025-04-05T14:14:49Z

Cooljerk: Created page with "DRAWING A TEXTURE First, we need to talk about how the dreamcast draws. The dreamcast does not draw like a modern GPU, it doesn’t have a GPU at all. It has a PVR Core which uses deferred rendering. The way this works is that a small amount of memory inside the Dreamcast VRAM is set aside to hold vertex data. Instead of rasterizing each polygon as they are sent to the dreamcast and immediately drawing it to the destination, the Dreamcast instead caches all polygons upfr..."

DRAWING A TEXTURE
First, we need to talk about how the dreamcast draws. The dreamcast does not draw like a modern GPU, it doesn’t have a GPU at all. It has a PVR Core which uses deferred rendering. The way this works is that a small amount of memory inside the Dreamcast VRAM is set aside to hold vertex data. Instead of rasterizing each polygon as they are sent to the dreamcast and immediately drawing it to the destination, the Dreamcast instead caches all polygons upfront into these memory bins, which are known as Object Polygon Buffers, or OPBs for short. One all the vertecies for the polygons in the scene are collected, you tell the dreamcast that the scene is done and it renders. This has a bunch of really cool added benefits, notably that you do not have to sort polygons for transparancies to work. Overdraw is also generally not a thing, since only the exact amount of pixels needed for the destination are drawn. Every single pixel drawn is depth tested against all polygons around it during rasterization. This means pixel perfect z-buffers!

There are 5 types of Object Polygon Buffers in VRAM, which determine attributes about the polygon rendered. They are the Opaque Polygon Bin, the Opaque Modifier Polygon Bin, the Translucent polygon bin, the Translucent modifier polygon bin, and the punch-thru polygon bin. The type of bin a vertex belongs to determines what kind of polygon it will be. Broadly, there are 3 types: Opaque, Translucent, and Punch-Thru. We’ll talk about modifier volumes later.

Opaque Polygons are fully visible, no holes in it. If it is texture mapped, then the texture cannot have an alpha channel in it, it must be only RGB.

Translucent Polygons are what we would think of as true-color 32-bit in modern computing. It means colors are represented as ARGB, providing an alpha channel. When used on a texture mapped polygon, the individual alpha channels of pixels in the texture determine the visibility. Instead of per-polygon transparency, the dreamcast does per-pixel! Pixels can be transparent in a range depending on the bitdepth.

An offshoot of Translucent Polygons are Punch-Thru polygons. Data-wise, these are basically the same as a translucent polygon, except any value in the alpha channel besides 0 is treated as 100% transparent. That means pixels are either entirely visible, or entirely transparent. It is said to “punch-through” because the transparent pixels look like holes punched through the polygon.

We need to determine how much VRAM space to give each one of these polygon bins. When we render our scene, we will send our vertices to one of these bins depending on how we want the resultant polygon to be drawn. We specify how much VRAM each bin gets in the pvr_init_params_t:
static pvr_init_params_t pvr_params = {
/* OPB (Object Polygon Buffer) Bin allocation table: */
{
PVR_BINSIZE_32, /* Enable Opaque Poly Bin: 32 word (128 byte) length */
PVR_BINSIZE_0, /* Enable Opaque Modifier Poly Bin: 32 word (128 byte) length */
PVR_BINSIZE_32, /* Enable Translucent Poly Bin: 32 word (128 byte) length */
PVR_BINSIZE_0, /* Enable Translucent Modifier Poly Bin: 32 word (128 byte) length */
PVR_BINSIZE_0 /* Enable Punch-thru Poly Bin: 32 word (128 byte) length */},
/* Vertex buffer size 512K */
512 * 1024,
/* DMA Enable: Off */
0,
/* FSAA Enable: Off*/
0,
/* Translucent Autosort Disable: Off */
0,
/* OPB Overflow count: Preallocates this many extra OPBs (sets of tile bins), allowing the PVR to use the extra space when there's too much geometry in the first OPB. */
0
};

The available sizes for allocation for each bin are as follows:
PVR_BINSIZE_0: 0-length, which disables the list
PVR_BINSIZE_8: 8-word (32-byte) length
PVR_BINSIZE_16: 16-word (64-byte) length
PVR_BINSIZE_32: 32-word (128-byte) length
In the above example, we’re allocating 128-bytes to the Opaque Polygon bin, and 128-bytes to the Translucent Polygon bin. With our VRAM memory allocated for our OPBs, it’s time to create some textures. Let’s define some pointers to vram memory in our source code as global variables:
pvr_ptr_t tex_blue;
pvr_ptr_t back_tex;

These pointers will hold the address of our textures in vram, making them our system handles for those textures. Let’s create a function that will let us allocate some memory for these textures in vram, then fill them up:
void textures_init(void) {
tex_blue = pvr_mem_malloc(128 * 128 * 2);
png_to_texture("/rd/blue.png", tex_blue, PNG_FULL_ALPHA);
back_tex = pvr_mem_malloc(512 * 512 * 2);
png_to_texture("/rd/background.png", back_tex, PNG_NO_ALPHA);
}

Our function begins by calling pvr_mem_malloc(). This function takes a number which represents how many bytes to allocate. We want enough room to hold all the pixels in our textures. Our Blue Texture is 128x128 pixels big, and the Dreamcast uses 16-bit color internally, despite supporting 24-bit color. 16-bits is the same as 2-bytes, which is where the 2 comes from in the above formula. Thus we need 2-bytes for each pixel, and there are 128x128 pixels. We can add the math into the parameters so it’s more readable. Pvr_mem_malloc returns the vram address where it allocated the space, which we save in our tex_blue pvr_ptr.

We do the same with back_tex. This time, our background.png image is 512x512 pixels big. We adjust the parameter to account, and store the pointer in the appropriate pvr_ptr.

We use each pointer to direct our png_to_texture function where to deposite the pixels it loads. png_to_texture opens a png file and returns the raw pixel data in a dreamcast pixel format. It takes a char* string that is the filepath to the png, along with a pvr_ptr that points to an allocated area of VRAM, and a flag. The flag determines how the function treats the png, and how it orders the data. There are 3 enums that an be set as the flag:
PNG_FULL_ALPHA: The png loaded has an alpha channel. It will be turned into ARGB4444.
PNG_NO_ALPHA: The png loaded has no alpha channel. It will be turned into RGB565.

PNG_MASK_ALPHA: The png loaded has an alpha channel, but will be a punch-thru texture. It will be turned into ARGB1555.

We will need to know the pixel format of the texture in a moment, so take note of which flag you have set. We used FULL_ALPHA for the blue texture, and NO_ALPHA for the background texture.

We need a function to call that will actually Submit vertices to the Dreamcast and command it to draw. We’ll call that function DrawFrame(), although that’s a misnomer. It’s actually just submitting frame data, and the frame is drawn later. Regardless of semantics, let’s create such a function:
void DrawFrame(void)
{
pvr_wait_ready();
pvr_scene_begin();
// Rendering code in here
pvr_scene_finish();
}

Our DrawFrame function begins with pvr_wait_ready(). This is a function that gets the PVR ready to accept vertices. This means doing some internal house keeping, as well as generally waiting for vblank to start a new frame. That means calling pvr_wait_ready(); ends the previous frame in a loop and waits for a new one to begin. If you call this twice in a loop, then your loop will run at 30 FPS. If you call it 3 times, your loop will run at 20 FPS. And so forth.

After the PVR is ready, we have a pair of calls, pvr_scene_begin() and pvr_scene_end. Everything that goes in between these calls encapsulates a full frame of the scene being drawn. In between these calls, we can further breakdown which polygon bin we are going to be working on:
pvr_list_begin(PVR_LIST_OP_POLY);
// Vertex code here for Opaque polygons
pvr_list_finish();

This is a pair of calls, pvr_list_begin(int) and pvr_list_finish(). pvr_list_begin takes an enum that tells it which list to bind. When a list is bound, all pvr functions will be directed towards that one. pvr_list_finish closes the bin for the scene, once a bin is closed it cannot be reopened until the next frame. In this example, we are opening the bin for opaque polygons, meaning any vertex we submit will go to that bin.

Inside our Opaque Polygon list functions, we can create vertices and submit them. We can also create a command to let the PVR know which texture we want to use when texture mapping the polygon. We need to first create some variables:
pvr_poly_cxt_t cxt;
pvr_poly_hdr_t hdr;
pvr_vertex_t vert;

First, we need to create a variable to hold our polygon context. A context is an instance of the polygon parameter data, encapsulated into an object. This context is where we set which texture to draw with for the next polygon, along with the parameters for the texture. Once we have our polygon context defined, we can compile it into a pvr polygon header. A PVR Polygon Header is an object that represents a command to the PVR to setup the next polygon. It is the same size as an vertex, and thus behaves like one. You submit the polygon header the same way you submit a vertex. In fact, you can store a bunch of vertices into an array, and insert polygon headers into the array, and submit all the polygon data at once, which we’ll get into later. For now, let’s concentrate on submitting one vertex (or header) at a time.

Our actual vertices will be stored in a structure called pvr_vertex_t. The Dreamcast and KOS have a number of predefined vertex types, which have more or less attributes depending on rendering mode. The more features a vertex or render mode has, the more space it consumes. Vertices are either 32-bytes big, or 64-bytes big. A special case is a Sprite object, which is 4 vertices squished together into one 64-byte object, meaning you can define a sprite in one vertex instead of needing 4 vertices. The types of vertices available are:
pvr_vertex_t: the generic, default vertex.
We are going with the default type. When we submit vertices to the PVR, we will use this variable and fill out the fields inside of it as needed.

Let’s begin by creating our Polygon context. We want to draw the background texture to the entire screen. We can do that like so:
pvr_poly_cxt_txr( &cxt, /* Destination Context */
PVR_LIST_OP_POLY, /* Flags */
PVR_TXRFMT_RGB565, /* Texture Format */
512, /* Texture Width */
512, /* Texture Height */
back_tex, /* TextureID */
PVR_FILTER_BILINEAR); /* Filtering */
pvr_poly_compile(&hdr, &cxt);
pvr_prim(&hdr, sizeof(hdr));

We need to create a polygon context for our background texture. We fill in the appropriate fields: this is going to the opaque polygon bin, the texture has no alpha channel so it’s RGB565, the width and height are 512x512, the pointer to the texture in memory is back_tex, and we will be using bilinear filtering. With this context object created, we compile it into our header. PVR_prim() is a function that takes a vertex or header file, and send its data over to the VRAM polygon bin. It takes a second parameter with a size to know how many bytes to send to VRAM. We send our header that tells our PVR that the next polygon renders with the back_tex using bilinear filtering as an opaque polygon.

Now, let’s set some general parameters for our vertices:
vert.argb = PVR_PACK_COLOR(1.0f, 1.0f, 1.0f, 1.0f);
vert.oargb = 0;
vert.flags = PVR_CMD_VERTEX;

Our vertex contains a field for an argb definition, to give the vertex a diffuse color. We set it to pure white, 1.0 (100%) in RGBA. Our vertex also has an offset argb value, this is for specular highlights. We’ll leave it set to 0, unused. We set a command in the flag field: PVR_CMD_VERTEX. This tells the PVR to begin taking in vertices for a polygon strip. When a command is given telling the PVR that it’s the EOL for the strip, it’ll end the polygon and move onto a new one.

With our general parameters set, lets begin making the actual position data in the vertices and uploading them to VRAM:
vert.x = 0.0f;
vert.y = 0.0f;
vert.z = 1.0f;
vert.u = 0.0f;
vert.v = 0.0f;
pvr_prim(&vert, sizeof(vert));

each one of these sections is a single vertex. We are manually changing the XYZ coordinates of the vertex, along with the UV coordinates, before sending it to the PVR. This vertex is at 0,0,1.
vert.x = 640.0f;
vert.y = 0.0f;
vert.z = 1.0f;
vert.u = 1.0f;
vert.v = 0.0f;
pvr_prim(&vert, sizeof(vert));

The next vertex resides at 640,0,1. Our two vertices so far have drawn a 640-pixel straight line from the left side of the screen to the right side, at Y position 0, which is the very top.
vert.x = 0.0f;
vert.y = 480.0f;
vert.z = 1.0f;
vert.u = 0.0f;
vert.v = 1.0f;
pvr_prim(&vert, sizeof(vert));

Our next vertex is at 0,480,1. This has shot back to the left side of the screen, then all the way down to the bottom row of pixels, Y at 480. This has formed a triangle between our previous 3 vertices. However, we have not given the command that this the end of line for the triangle strip, so we can submit another vertex.
vert.x = 640.0f;
vert.y = 480.0f;
vert.z = 1.0f;
vert.u = 1.0f;
vert.v = 1.0f;
vert.flags = PVR_CMD_VERTEX_EOL;
pvr_prim(&vert, sizeof(vert));

This final vertex is at 640,480,1. It’s at the very bottom right corner of the screen. Given the previous 3 vertices, this forms a second triangle, with the area of both filling the entire 640x480 screen. We pack a command into the flag of this final vertex, “PVR_CMD_VERTEX_EOL.” This tells the PVR that this strip of 4 vertices is a single long polygon that is finished. In the end, we wound up defining a screen-filling square and filled it with our back_tex.
Place this call within our Main() loop and run the program, and we should get the background texture filling our screen:
while(Game.Done == 0)
{
//Counter++;
EvHandler.PollEvent(&Game);
HandleInput(&Game);
DrawFrame(); }

We have successfully loaded and displayed a texture. We will come back shortly and continue learning how to use the PVR. However, our program currently has no way of responding, every time we want to make a change we have to turn off the dreamcast and wait for it to boot back up. Let’s give ourselves the ability to communicate with our program using our gamepads.