sdl-gpu
sdl-gpu copied to clipboard
grimfang4
Any full documentation or files to use sdl gpu to build a game framework
i built a game engine using sdl gpu , i am trying to make it bigger ( like a game framework ) to add are more capabilities , the problem is that i find my self many times obliged to edit sdl_gpu and fix some issues , that is not going greate without a full documentation , i know this documentation " http://dinomage.com/reference/SDL_gpu/index.html " it is not helping alot , not helping with the inner implementation of the functions im dealing with , where can i find some files , or any kind of informations that helps me here , im sure that there where some sort of a team that worked on sdl_gpu and offred to one an other some explanation , can i get that ?
Yes, of course it's important. The biggest obstacle is that I'm the core developer and haven't had much time lately. I wrote all of the structure and implementations of almost every function. The internal/implementation documentation of SDL_gpu is solely via comments in the source, and yes, it would be great to improve that.
Can you tell me more specifically what I can help you with?
im building a crossplatform game making studio ( android / ios / windows / mac .. ) for the moment 2D games , i want to merge sdl_gpu with my game engine , but i don't want to blowup everything , i want to know exactly what ill be doing, so i need to understand everything about sdl_gpu
Well, since I'm more or less comfortable with all of it, you'd be more help in determining where, precisely, the documentation is lacking. Just ask me about a function or subsystem and I'll tell you all I know.
Without specific questions, I can only really describe the structure of the project. If any of these details are useful, we can work them back into the documentation.
At the surface level, SDL_gpu is a collection of source files:
Headers:
SDL_gpu.h <-- Exposes all structures and functions for normal use
SDL_gpu_RendererImpl.h <-- Use this if you need to write your own renderer
SDL_gpu_OpenGL* <-- OpenGL version-specific structures and shaders so you can drill down into SDL_gpu's opaque data structures if needed
SDL_gpu_GLES* <-- OpenGL ES version-specific structures and shaders so you can drill down into SDL_gpu's opaque data structures if needed
Implementations:
SDL_gpu.c <-- Implementations of standard SDL_gpu functionality and state changes or wrappers over the generic renderer interface, which will forward the arguments to the renderer-specific implementation
SDL_gpu_renderer.c <-- Implementations of functions directly related to the generic renderer interface and organizational state
SDL_gpu_shapes.c <-- Wrappers for the renderer-specific implementations of graphics primitives
SDL_gpu_matrix.c <-- Implementations for all matrix manipulation functions
renderer_OpenGL_* and renderer_GLES_* <-- Concrete implementation files for each renderer. They set up the specific details of the renderer, then pull in the unified GL files
renderer_GL_common.inl and renderer_shapes_GL_common.inl <-- Unified GL files for renderer-specific implementations of graphic and state change functions that is set up by the preprocessor definitions in the concrete implementation file
externals/ <-- SDL_gpu can use bundled versions of GLEW, stb-image, and stb-image-write. The bundled version of GLEW is modified to support GL 3+ properly, so be aware that system GLEW may not actually work.
thanks , i think it would be a good idea to leave this issue as an open documentation , i won't be annoying by asking , i'ill just ask some important questions that will help others to continue sdl_gpu development
@grimfang4 On this topic, would you be able to give an overview of SDL_gpu's architecture? For example, does it use the immediate pipeline or is it somehow based on shaders?
I think this is related to #70: I'm missing a basic architectural understanding on how to make SDL_gpu code perform well
Yeah, here's a little overview of how SDL_gpu interacts with OpenGL:
Function calls and SDL_gpu's data structures are passed through a chosen renderer. The renderer implements the interface between the SDL_gpu API and OpenGL. Each built-in renderer represents a major version of OpenGL from 1 to 4 or OpenGL ES from 1 to 3. The renderer creates contexts as necessary and hides other stuff that is OpenGL-specific.
All of the later renderers (OpenGL 2+ and GLES 2+) use the programmable pipeline only. Some renderers are capable of using the old fixed-function pipeline via either glBegin/glEnd (e.g. GL 1) or array upload (e.g. GLES 1). You are very unlikely to end up using the fixed-function pipeline on any device at all. SDL_gpu keeps two shader programs internally for any given renderer. One shader is for textured blits and the other is for untextured blits (e.g. shapes).
When SDL_gpu does its rendering, the textures themselves stay as-is on the GPU. The only things that SDL_gpu may upload by itself each blit or each frame are the VBO that stores the vertex position, texcoord, and color data (usually 4 vertices per blit) and the IBO/EBO that stores indices into the VBO (usually 6 indices per blit). There is a performance difference when considering how this data goes to the GPU that depends on your device. You can #define SDL_GPU_USE_BUFFER_MAPPING or SDL_GPU_USE_BUFFER_RESET when building SDL_gpu to try different upload methods. Please do let me know your device model, OS version, and which of these modes works best for you.
SDL_gpu does implement a basic form of batching. It will hold on to all of the pending blits and upload the data in the VBO to the GPU all at once, as needed. This most often occurs either when the texture is changed (i.e. GPU_Blit() is called with a different image) or when GPU_Flip() is called.
@grimfang4 this is very useful information! I'm now certain that SDL_gpu is doing what I'd expect it to internally (assuming it's working as planned). It'd be great to get this info into the docs somehow, but would understand if it doesn't have the highest of priorities at the moment..
i will start documenting sdl_gpu for you , from today , a i will write e detailed explanation of a function each day , no need to explain how sdl_gpu usees renders .... because you have done that , so ill pass to the next step and explain the logic of each function ... how this helps ? it will make people able to understand how sdl_gpu works exatly and then be able to modify it for custom versions of their engines , then we get more users , and also it will help tracking bugs andnoticingmissing functionilities .... , you can open back this issue and ill start from tomorrow with GPU_Init() im sure other people will join me
That would be great. It's much easier for me personally to edit documentation, so I'll accept any new documentation pull requests you come up with.
GPU_Init() java doc style : /**
- Initializes sdl_gpu and creates a window and returns a pointer to the window's target
- @param w window width in pixels
- @param h window height in pixels
- @param SDL_flags the flags to pass to SDL when creating the window
- @return window's target
**/ Details : 1- Initialize 'error queue' , that is the queue used to store error informations see how 'gpu_init_error_queue()' works , the error queue is filled used GPU_PushErrorCode() 2 - Initialize 'renderer register' , that is creating an array of information about the supported renderers on the current platform those information are the renderer name and id and create/free functions 3- initialize SDL library normaly using SDL_Init , first we check if SDL was previously initialized by checkcing _gpu_initialized_SDL_core flag and calling SDL_WasInit(SDL_INIT_EVERYTHING) , if both are false we initialize the sdl video subsystem , note that we do that twice to be sure that SDL_gpu keeps it available until GPU_Quit() 4- walk throught all registred renderers and for each we try to initialise it , when one of them succeed on creating a window we return that window see how GPU_InitRendererByID() works
Notes : Read more about GPU_RendererID
( Please improve this )
i was waiting for your reply to let me know if thats the kind of documentation you i am supposed to right ? i mean it that fine and eough ? what should i write about functions ... ?
Sorry, been distracted from this. This is great and I thank you for putting it together. I worked your suggestion into commit 3444a28b310d7b5071f116eafc5b3ece25fc92c2. I took out a couple of things that were implementation details, but they might be good to put into the implementation comments (i.e. in SDL_gpu.c).
Where can we find this improved documentation please?
Is there any place which explains, for example, why and when calling GPU_FlushBlitBuffer() or other general concepts of the lib?
Where can we find this improved documentation please? Is there any place which explains, for example, why and when calling
GPU_FlushBlitBuffer()or other general concepts of the lib?
@fralbo , hi , i saw that need , and i tried to help with this issue , but i ended-up being so busy to do it , sorry for that