D
Deleted User
Guest
OP
Hello all! Recently, I have been learning more and more C++/C and decided that I wanted to go into homebrew development. I've had ideas like this in the past, but they are finally bearing their fruit! In this, I had to learn about Citro3D (also known as C3D). I have decided to create a comprehensive, multi-chapter guide for using Citro3D. There have been a few of these in the past, but I really want to go in depth about using Citro3D, specifically for 2D applications, since those are more common than 3D applications. These mini-chapters are also learning experiences for me, so if you find any errors in one of my explanations, please don't hesitate to correct me!
This chapter is all about introducing Citro3D and explaining how it works and why it does. I will do my best to explain it in a non-frightening way. I won't be going into any explicit function calls for this chapter, because it is an introduction. Those will be included in later installments. Thanks for reading!
Many homebrew developers include some sort of graphics system in their code. Whether it be for drawing rectangles or text to the screen, or drawing a fidget spinner (sigh), it has to exist. So, how does this happen?
Probably the most easy-to-use graphics system is a graphics library such as PP2D, or SF2D (although it is now deprecated), because they don't require more setup than an initializer function. But would it surprise you to learn that these libraries are actually just wrappers of Citro3D? It probably shouldn't considering the authors declare that they are wrappers and not actually individually developed libraries, but nonetheless, Citro3D is still the base. This is because Citro3D is a library that communicates with the 3DS' GPU. The GPU (Graphics Processing Unit) is a piece of hardware included in most modern machines to provide a separate area from the CPU to calculate and render images (or frames) that get pushed to the screen/monitor. These are very important because if you had to render everything with the CPU (termed CPU rendering) it would greatly hinder the speed of the program. Imagine having an author and an artist for the same book. The author gets to focus on writing the plot and enhancing it to make the book appealing and well-written, whereas the artist focuses on the images that get included in the book. If they were both done by one person, both efforts would be affected negatively and the whole process would take a lot longer; however, done separately the speed is greatly increased as both people are specifically good at one thing.
So, Citro3D communicates with the GPU then, right? That is correct! It is called a library, a term any programmer should be familiar with. It is already included with ctrulib (libctru?) and is automatically installed when using the devkitPro installer.
Well, if Citro3D communicates with the GPU, how does it do it? To answer this question, we first must understand some things about the GPU.
However, this is not actually the file name. The real file name is "vshader.v.pica"; however, it compiles under a different name. This is what PP2D (a 2D graphics wrapper for Citro3D) is using for it's "vshader.v.pica".
The shader is written using picasso, which was created by the author of Citro3D, and is a slightly modified version of assembly. I don't know much about it, and personally I use the one from PP2D in all of my applications since it works great. You can see a guide to writing your own shader here.
Now the second point. Using triangles as its base actually isn't an uncommon thing. All polygons (not including circles since they aren't technically polygons) can be created from triangles, unlike squares. This is especially useful when creating 3D models, and can be useful for creating 2D shapes as well. We will actually cover this more in a later installment where we create our own N-gons (polygons with N sides).
Although this series will be exclusively dealing with 2D applications, it is important to know that Citro3D also supports 3D shapes (hence the "3D").
3DBrew.org already has a very nice guide for users looking to setup a development environment if they haven't already. So if you haven't ever installed devkitPro, make sure you follow this guide to set it up.
Once you have devkitPro installed, go ahead and download the following ZIP file and extract it to a proper development environment (a path that doesn't have any spaces in it).
C Users.
C++ Users.
Both of these will contain the exact same code in the end. I will personally be programming in C, but if you are using the C++ variant and find that some code doesn't work (i.e. not supported) let me know and I will do my best to find a universal solution.
Note: If you did not use the default devkitPro installation location, make sure you edit the "transmit.bat" to fit the actual file path. You also have to do this if you are on Linux as most (if not all) distros do not support BAT extensions.
Place the source, include, resources, Makefile, and transmit.bat items in a folder named "Citro3D". (If you choose a different name, you need to edit the "Citro3D.3dsx" in transmit.bat to "<foldername>.3dsx")
In the end, your setup should match the following:
Note that the path would be C:\Homebrew_Applications\Citro3D and that there are no spaces.
For this series, you would do best to make sure you have a decent text editor. Once that has language support as well as multi-panel support (multiple files open in one window). So no, Windows Notepad will not work. However, there are options such as Notepad++ or Atom that both have language support, multi-panel support, and even theme support so you don't want to stab your eyes out!
That is it for today's chapter guys! Thank you for reading. I plan on including quite a few more installments if this one is received well. If you have any questions that weren't addressed in this chapter, don't hesitate to ask as I might have missed something. I am willing to explain to the extent of my knowledge but if I don't know, I won't make something up.
Thanks guys!
This chapter is shorter than most of the others will be mainly because this chapter isn't explaining any code. Future chapters will definitely be longer and might take longer to come out depending on their content.
fincs: Author of Citro3D and Picasso.
Bernardo Giordano: Author of PP2D.
xerpi: Author of SF2D.
kprovost7314: Author of the Citro3D guide that taught me some of what I know and inspired me to make this series.
This chapter is all about introducing Citro3D and explaining how it works and why it does. I will do my best to explain it in a non-frightening way. I won't be going into any explicit function calls for this chapter, because it is an introduction. Those will be included in later installments. Thanks for reading!
What is Citro3D?
Probably the most easy-to-use graphics system is a graphics library such as PP2D, or SF2D (although it is now deprecated), because they don't require more setup than an initializer function. But would it surprise you to learn that these libraries are actually just wrappers of Citro3D? It probably shouldn't considering the authors declare that they are wrappers and not actually individually developed libraries, but nonetheless, Citro3D is still the base. This is because Citro3D is a library that communicates with the 3DS' GPU. The GPU (Graphics Processing Unit) is a piece of hardware included in most modern machines to provide a separate area from the CPU to calculate and render images (or frames) that get pushed to the screen/monitor. These are very important because if you had to render everything with the CPU (termed CPU rendering) it would greatly hinder the speed of the program. Imagine having an author and an artist for the same book. The author gets to focus on writing the plot and enhancing it to make the book appealing and well-written, whereas the artist focuses on the images that get included in the book. If they were both done by one person, both efforts would be affected negatively and the whole process would take a lot longer; however, done separately the speed is greatly increased as both people are specifically good at one thing.
So, Citro3D communicates with the GPU then, right? That is correct! It is called a library, a term any programmer should be familiar with. It is already included with ctrulib (libctru?) and is automatically installed when using the devkitPro installer.
Well, if Citro3D communicates with the GPU, how does it do it? To answer this question, we first must understand some things about the GPU.
1. It is a PICA200 unit. (i wish I could explain more)
2. All of it's rendering is done using triangles as its base.
Let's go over the first one really quick. If you are a C/C++ programmer, you most likely don't deal with assembly very often. In fact, it might not even be a term that you have heard before! Assembly is the most low level yet comprehensible programming language there is. In fact, it is so low level that compilers automatically take care of it for you, because if you had to type out every single assembly instruction you would be there for a very, very long time. The GPU uses shaders for rendering (this is a guess, if anybody wants to tell me what it actually is for I would appreciate it). Most applications include this file with the following include statement:2. All of it's rendering is done using triangles as its base.
Code:
#include "vshader_shbin.h"The shader is written using picasso, which was created by the author of Citro3D, and is a slightly modified version of assembly. I don't know much about it, and personally I use the one from PP2D in all of my applications since it works great. You can see a guide to writing your own shader here.
Now the second point. Using triangles as its base actually isn't an uncommon thing. All polygons (not including circles since they aren't technically polygons) can be created from triangles, unlike squares. This is especially useful when creating 3D models, and can be useful for creating 2D shapes as well. We will actually cover this more in a later installment where we create our own N-gons (polygons with N sides).
Although this series will be exclusively dealing with 2D applications, it is important to know that Citro3D also supports 3D shapes (hence the "3D").
Setting Up The Environment
Once you have devkitPro installed, go ahead and download the following ZIP file and extract it to a proper development environment (a path that doesn't have any spaces in it).
C Users.
C++ Users.
Both of these will contain the exact same code in the end. I will personally be programming in C, but if you are using the C++ variant and find that some code doesn't work (i.e. not supported) let me know and I will do my best to find a universal solution.
Note: If you did not use the default devkitPro installation location, make sure you edit the "transmit.bat" to fit the actual file path. You also have to do this if you are on Linux as most (if not all) distros do not support BAT extensions.
Place the source, include, resources, Makefile, and transmit.bat items in a folder named "Citro3D". (If you choose a different name, you need to edit the "Citro3D.3dsx" in transmit.bat to "<foldername>.3dsx")
In the end, your setup should match the following:
Note that the path would be C:\Homebrew_Applications\Citro3D and that there are no spaces.
For this series, you would do best to make sure you have a decent text editor. Once that has language support as well as multi-panel support (multiple files open in one window). So no, Windows Notepad will not work. However, there are options such as Notepad++ or Atom that both have language support, multi-panel support, and even theme support so you don't want to stab your eyes out!
That is it for today's chapter guys! Thank you for reading. I plan on including quite a few more installments if this one is received well. If you have any questions that weren't addressed in this chapter, don't hesitate to ask as I might have missed something. I am willing to explain to the extent of my knowledge but if I don't know, I won't make something up.
Thanks guys!
This chapter is shorter than most of the others will be mainly because this chapter isn't explaining any code. Future chapters will definitely be longer and might take longer to come out depending on their content.
Credits
Bernardo Giordano: Author of PP2D.
xerpi: Author of SF2D.
kprovost7314: Author of the Citro3D guide that taught me some of what I know and inspired me to make this series.
Last edited by ,
