PSPSDK Header Information

[Vincent]

I've decided to make a sticky thread that'll explain what certain header files do in the pspsdk. I've learned a GREAT deal from just reading through these files. Hopefully, I can provide a great deal of documentation for each of these files in the end, so that it will help people understand how the pspsdk works much better, and makes them better quicker.

My goal here, is to list every file in the pspdev/psp/sdk/include folder with an accurate and complete description of the file, and maybe explain a little bit on some functions that are particularly interesting. That way, it might help people research the pspsdk. My personal gain from this is to hopefully understand the pspsdk much more, so I can tackle more in-depth concepts (or at least in my opinion), and it could help those who have had those same questions.

I don't know what every single file does, but I'll post a little information on the ones I do know. If anyone has information on a file that I didn't list, or have more information on a header file I have already written about, please tell me! The file descriptions that I feel that are incomplete will be tagged as '[PENDING]', and the ones that are done will be tagged '[DONE]'.

These files can be found in:
"C:\cygwin/usr/local/pspdev/psp/sdk/include" for cygwin users on Windows, and
"FileSystem:\usr/local/pspdev/psp/sdk/include" for Linux users (or Ubuntu users at least, I think). FileSystem is your C drive by the way.

pspctrl.h [PENDING]
This header file contains the functionality for developers to harness the PSP's input. The enumeration, SceCtrlButtons contains all the different values for the PSP's input buttons. It also contains coordinates, which I think are Cartesian coordinates, of the analog stick. You may want to convert them into polar coordinates so that your character's movement doesn't increase when the analog is pushed diagonally. The enumeration, SceCtrlMode, contains two states: PSP_CTRL_MODE_DIGITAL, PSP_CTRL_MODE_ANALOG. I know that setting int sceCtrlSetSamplingCycle(int cycle) to PSP_CRTL_MODE_ANALOG enables the use of the analog stick, but not too sure about how sceCtrlSetSamplingCycle, or the other functions similar to that works, but I know it has something to do with the the detail of the analog mode? You can use
sceCtrlPeekBufferPositive(SceCtrlData *pad_data, int count)
to check whether a button has been pushed and
sceCtrlPeekBufferNegative(SceCtrlData *pad_data, int count)
to see if a button hasn't been pressed (or released?) by passing the address of an SceCtrlData structure. There's a little in there about latching buttons, is that a simple way to lock a button? Just wondering...


pspgu.h [PENDING]
This is a huge, and monstrous file that contains the functions for using the PSP's GU. If you really want to get good to do anything graphically with the PSP, this is a great starting point, and it's simple to do. There's a good deal of information for each function, macro, and structure listed in it, and if you have any problems, try googling the topic (because the information you're probably looking for like 'how alpha blending works' can be found via google, or gamedev.net). If that fails, the forum is a great place to ask! I'll go into more detail later.

pspgum.h [PENDING]
This is the header file that contains the functions for using matrices, and manipulating them. It also contains the means for controlling which matrix mode you're in: GU_PROJECTION for projection, GU_VIEW for view, and GU_MODEL for model. There's also another matrix mode called GU_TEXTURE. Not quite sure what it does, but I believe it has something to do with moving/shifting texture around on a surface maybe? Again, just a wild guess. There's also another set of drawing functions that are the same to the sceGuDrawArray() functions found in pspgu.h. This one is called: sceGumDrawArray(), and there are 3 more functions similar to it. From the information I've come across, they do the same things. I'm guessing they perform these functions on different pipelines based on sceGuDrawArray(), or sceGumDrawArray(). I'm basing this on nothing though, except for a theory. It's probably wrong until clarified. I use sceGumDrawArray() when drawing all my scenes.

pspge.h [PENDING]
This if a file I need to look into much more carefully. It is a bit similar to pspgu.h, but it contains functions, enumerations, and structures for vertex skinning and bone matrices. These are for doing mesh animations. The functions in here contribute both to pspgu.h and pspgum.h in a way. I believe that these three files work together closely as powerful trio.

psprtc.h [PENDING]
Not much to mention here for now seeing that I'm running out of time, but I would like to inform that this is the file that contains time data for doing things on the PSP that involve using timers and such. This header file contains the means of allowing the programmer to set a tick count in microseconds (one millionth of a second) of timer precision. There's also a useful structure called pspTime that contains information a set of members for the time, day, month, etc. Interesting stuff, but rest assured, this is an extremely useful header to use if you're doing something like using a countdown timer, or doing benchmarks to see how long it takes to do calculations or other operations on the PSP.

This concludes my session so far. I'm out of time, and I hope to get more time later on to continue on with this. If anyone finds any data/information that's incomplete or irrelevant, please tell me, and I'll change it. Again, if anyone would like to share their own documentation for how a header file works, please fill me in.

[Raphael]

Nice idea, if only it wasn't consisting merely of wild guesses at the moment (and quite some wrong) and instead of facts :/ I'll try to give some explanations on what is wrong and what not when I find time.

[Vincent]

I imagined it to start out as a few guesses with some credible information, but as time goes on, I hope to add to it will others' responses, and then we'll all have another good resource on these forums to look at. I want this thread to help lead to a better understanding of how the pspsdk works, and to document its functions. That way, we can eliminate questions that haven't even been asked yet, and it will make other beginners like me better quicker without having to ask questions that stump us, and sit tight while waiting for a reply. I'm guilty for doing that plenty.

[Raphael]

pspctrl.h [PENDING]
[...]It also contains coordinates, which I think are Cartesian coordinates, of the analog stick. You may want to convert them into polar coordinates so that your character's movement doesn't increase when the analog is pushed diagonally.

?? What are you aiming at and how do polar coordinates avoid moving diagonally? Also converting to polar coordinates isn't what you want in most cases. Actually, this doesn't clarify at all how the analog coordinates are supposed to be read.
First thing to mention would be that they are stored as unsigned char (range 0 - 255) and need to be offset by -128 to get the real values.

The enumeration, SceCtrlMode, contains two states: PSP_CTRL_MODE_DIGITAL, PSP_CTRL_MODE_ANALOG. I know that setting int sceCtrlSetSamplingCycle(int cycle) to PSP_CRTL_MODE_ANALOG enables the use of the analog stick, but not too sure about how sceCtrlSetSamplingCycle, or the other functions similar to that works, but I know it has something to do with the the detail of the analog mode?

That first SetSamplingCycle is supposed to be SetSamplingMode. Also SetSamplingCycle afaik sets the update frequency of the input. Normally you should keep it at 0.

You can use
sceCtrlPeekBufferPositive(SceCtrlData *pad_data, int count)
to check whether a button has been pushed and

...to check which buttons are currently pressed
[/quote]
sceCtrlPeekBufferNegative(SceCtrlData *pad_data, int count)
to see if a button hasn't been pressed (or released?) by passing the address of an SceCtrlData structure.
[/quote]
which buttons aren't currently pressed (basically just ~positive).

pspgum.h [PENDING]
[...]
 There's also another matrix mode called GU_TEXTURE. Not quite sure what it does, but I believe it has something to do with moving/shifting texture around on a surface maybe? Again, just a wild guess.

It changes the texture matrix that defines how texture coordinates are transformed before being used for texturing. With that you can easily rotate, scale or even project textures onto surfaces without changing the u/v values in the vertex array.
You need to set the sceGuTexMapMode to GU_TEXTURE_MATRIX for it to work.

There's also another set of drawing functions that are the same to the sceGuDrawArray() functions found in pspgu.h. This one is called: sceGumDrawArray(), and there are 3 more functions similar to it. From the information I've come across, they do the same things. I'm guessing they perform these functions on different pipelines based on sceGuDrawArray(), or sceGumDrawArray(). I'm basing this on nothing though, except for a theory. It's probably wrong until clarified. I use sceGumDrawArray() when drawing all my scenes.

Uh... that's completely off. They don't use different pipelines or anything. All they do is update the matrix states by calling sceGuSetMatrix and afterwards call sceGuDraw*. Hence those functions are matrix-aware and need to be used if you use gum to handle matrices.

pspge.h [PENDING]
This if a file I need to look into much more carefully. It is a bit similar to pspgu.h, but it contains functions, enumerations, and structures for vertex skinning and bone matrices. These are for doing mesh animations. The functions in here contribute both to pspgu.h and pspgum.h in a way. I believe that these three files work together closely as powerful trio.

It doesn't contain structures for vertex skinning or bone matrices really. It just contains a function that allows you to get any of the current set matrices (only after a sceGumUpdateMatrix() call in case you use gum) and further all functions required to send display lists and sync to the GE. Normally, you should never need to use those functions directly. All you need is wrapped in pspgu.
Pspge is basically the most direct hardware interface to the GE hardware and pspgu is just a wrapper library that eases the filling of display lists.

psprtc.h [PENDING]
Not much to mention here for now seeing that I'm running out of time, but I would like to inform that this is the file that contains time data for doing things on the PSP that involve using timers and such. This header file contains the means of allowing the programmer to set a tick count in microseconds (one millionth of a second) of timer precision.

Psprtc is just the RTC (realtime clock) interface of the psp. Every computer has a RTC, else it wouldn't be able to know the current date or show the time. It's basically just a hardware counter that counts at a specific frequency. When you then poll the current tick count and translate it into a human meaningful measure (like hours,minutes,seconds - which is possible because the interval of each tick is constant, so you normally have n ticks per second) you can retrieve the current time and date. With that you can naturally also implement timers.
Psprtc is just an interface to that piece of hardware and provides functions to easily convert between the hardware ticks and different time/date formats, like pspTime, the std C time_t or DOS/Windows times. Also it has some functions to check for leap years, the day of week or number of days in a specific month.
You CANNOT SET the time of the psp or the hardware counter with this library though!

[pspleio]

So nice.
i also refer to pspsdkdocs,but i think ur summary about head files is very useful!

[fil96]

0_0 Whoa, never knew the psp had so many great functions!

Great job vincent!