well, I meant so's people can edit the API docs easily... =) rather than having all changes go through admins which is a bit of a rigmarole!
but I guess that is hard to do if the API docs are part of the source. hmm!
Besides, there's also a Irrlicht Wiki where articles could be written. In the 'Code Snippets' section, there're even entries which explain one single function call.
Generated Documentation for BlindSide's irrNetLite. "When I heard birds chirping, I knew I didn't have much time left before my mind would go." - clinko
wITTus wrote:Besides, there's also a Irrlicht Wiki where articles could be written. In the 'Code Snippets' section, there're even entries which explain one single function call.
it's nothing at all like an API documentation, all in one place. And unless someone tediously did an entry for each method then we have exactly the same situation this topic asks about.
but never mind, if the docs are to believed we can "just send a email to the author of the engine" with any questions
One thing I appreciated much on the 1.5 release, is the update of the examples. New added features were demonstrated and that made a big change for me from the previous releases.
In the new releases, I would really like that we continue in that direction, and if more people (Not always the DEVS like Hybrid, Bitplane, etc. to do it) could commit on updating infos on the docs and examples would be great.
Since I'm more of a level designer than a programmer; If IRRlicht need some 3D assets (Levels or specific meshes) that could be needed for the examples, just send me a PM, I'll try to give something back.
In my spare time, now I'm trying to convert levels made in Hammer (Source Engine) directly to IRRlicht. It currently work exept for the Lightmaps.
I find myself in the situation where I have to add a new mesh type, one that performs no morphing or animation, just some props with lightmaps (houses, terrain things like that).
I have already specialized meshclasses which I developed in the past with my own hardware buffers which I added to the DX9 driver myself (DX8 is outdated and frankly I never understood why ppl want to use OpenGL as the underlying device when they work with the library that abstracts the graphic system 99% of the time). Why did I add my own meshes? Simply because I couldn't figure out how to create a mesh with the Irrlicht provided classes other than to let the Irrlicht system load an object in one of the proprietary file formats. That won't do for my project so I need to be able to assemble meshes from my own files.
I found it easier to modify the driver to add support for vertex and index buffer myself, because other than the hookup location into irrlicht all I needed was DX knowledge, and DX is better documented than irrlicht.
Now I need to add another option and I thought, maybe I should try to use the mesh stuff that's provided by irrlicht instead of modifying my own stuff so that my future code is more compatible.
I am now trying to figure out how to do this. I am finding myself staring at parts of the documentary like the following:
irr::scene::SMD3MeshBuffer Struct Reference Holding Frame Data for a Mesh
irr::scene::SMD3Mesh Struct Reference Holding Frames Buffers and Tag Infos.
irr::scene::IMesh Class Reference Class for accessing a mesh with multiple mesh buffers
and so on, I spare you more examples. The point is, if you have only a general idea of what a meshbuffer is and what it does but don't know the exact way this specific buffer is used, it is nearly impossible to use it, except by investing a significant amount of time to dig through the code, singlestep into it, analyzing the variables and so on. Perhaps only to find out in the end that the class doesn't do what I guessed it would. It is much easier to develop the whole stuff myself.
That's what I am probably doing for the props with the lightmaps again.
In my opinion Irrlicht is good for two things:
A) if you are stuck with properietary formats, you can use some common tools like scene editors, probably some simple modeling tools or converters to create a game level that resembles a quake or ogre or whatever scene/level, load that and do some simple things in it. You can figure out how to do this by using the supplied tutorials, which is where their usefulness ends.
B) Use it as a framework to do the routine stuff in DirectX like initializing, dealing with the more complex aspect of DX and then use the scengraph to place your own nodes and overload the render functions and then draw your own objects through the driver access functions with the primitive drawing functions.
I am obviously using solution B and the reason why I can't use it in a scenario C) where I can utilize the probably great power of the supplied interfaces and classes is because of lack of documentation. I don't have the time to analyze the engine and then supply my comments as an addon, perhaps to fund them rejected because I made a mistake or for some other reasons. Open Source is great for libraries like this one, but there are people who actually want to USE the library and not participate in the development. Irrlicht in it's current state with regard to the doeumentation, like so many other libraris, is a playing field for the main developers, some semi attched people who contribute loosely and for the rest of us, we are mainly left with staring in awe at the screenshots and demos.
If you want to elevate Irrlicht one day above this fate that you share with the vast majority of other Open Source products, you need an extensive documentation. There's a reason people are willing to pay for a commercial product and that reason is not so much a better quality but the fact that they can use it out of the box.
As for me, I am stuck with Irrlicht for now because it is too deeply interwoven in my code. If I had the choice again now, I would go with a commercial library that has a documentation.
Have you considering hiring a IRRlicht developper to give you theses docs since you don't want to take the time and research the code?
Do you know that it cost about a million box to have a Unreal License, and you want all that for nothing?! (I'm not meaning that IRRlicht is as good as the Unreal engine. Just the engine part)
A complete and fully documented information on an engine require a lot of time. You have some choices:
- Work on it on YOUR time if you're good in C++ programming
- Get somebody that will do this for you free (if you can)
- Pay someone to do this for you
- Ask politely on the forum if there would be some volunteer that would be willing to update the docs with your required details.
- lead a side project to update the docs and ask for volunteers..
- Get a commercial engine and then start complaining
I didnt read all your message, but I don't like when people are complaining about a open source project comparing it with a commercial solution saying it's not good, your last sentence looked like someone who would like a refund!
christianclavet wrote:Wow! That's as pretty dull comment!
People like you are the reason why a forum is not a good replacement for a documentation and why Open Source projects will never get the acceptance commercial products have. I have too much to do to come to forums for help and then find insults half of the time.
playerdark wrote:
I find myself in the situation where I have to add a new mesh type, one that performs no morphing or animation, just some props with lightmaps (houses, terrain things like that).
There's obviously no need to do this in your own class. We have an IMeshSceneNode and you can directly use it. Starting from the addMeshSceneNode method in the scene manager and navigating down the links you find in the API docs will be enough for an average programmer. But we also planned for another example showing the use of meshbuffers etc.
DX8 is outdated and frankly I never understood why ppl want to use OpenGL as the underlying device when they work with the library that abstracts the graphic system 99% of the time
Don't know which library you're speaking about here, but DX9 definitely is not what you're describing here. Moreover, you seem to miss some very important things about cross platform development etc.
nevertheless he got a point. The description of some interfaces are sparsely. Btw. @ref is almost unused at the docu, or missed I an other "look at" doxygen syntax?
So i missed the other look up syntax . Maybe adding some "used by" refs and "used for" descriptions will increase the userfriendlyness? Maybe someone who is annoyed by the docu can sarifice some time to improve it? With the support of the devteam and the community it shouldnt be a problem, or?
. Maybe adding some "used by" refs and "used for" descriptions will increase the userfriendlyness? Maybe someone who is annoyed by the docu can sarifice some time to improve it? With the support of the devteam and the community it shouldnt be a problem, or?