Raydium 3D Game Engine

Bonjour à tous,
je bosse actuellement sur une documentation détaillée des API de Raydium, en Français.
J'ai démarré par les API sonores.
Vous pouvez en avoir un petit aperçu en allant voir sur : http://www.benicourt.com/download/API_Raydium.doc
J'attends vos commentaires et suggestions.

_________________
Life is Hard, and then you die.

salut
c'est bien , mais je crois que tu peux arrêter de faire ça comme tu le fait
Xfennec a fait un script qui upload la doc qui est dans les sources (je suis pas sur la) directement sur le wiki donc ça ne te sert à rien de faire la doc sous world
Dsl

Oui, je sais bien qu'il y a déjà une doc avec des API, mais j'ai toujours préféré les manuels de ce type ;o). j'ai pas trouvé par contre de doc automatisée sur le Wiki.

J'ai dû mal à me repérer avec la doc existante, c'est le pourquoi de cette dernière. C'est juste un manuel de référence. Et puis c'est pour l'avoir en français même si j'ai pas trop de soucis avec l'anglais.

Mais bon, si cela n'intéresse personne, dites le moi, je le ferai à ma sauce dans mon coin.

Y-a de nombreux éléments qu'il faudrait documenter: il y a des petites choses comme le volume, c'est entre 0 et combien ?
ça parait bête, mais sans cela, le moteur est difficile à utiliser. Y-a de nombreux paramètres dans ce style, la liste des variables globales, ... Sans cela, comment développer ? Moi je veux bien faire des petits tests style test6.c, mais je ne veux pas rester simple utilisateur. J'ai envie de faire progresser le moteur. Tu comprends ?

Je viens juste de me joindre au projet et c'est vrai que même si j'ai du lire plus de la moitié de tout ce qui est contenu sur le site (ce qui représente plus d'une dizaine d'heures de lecture), je n'arrive pas à comprendre comment vous fonctionnez.

On dirait qu'il y a deux ou 3 codeurs, et que le reste se contente de faire des objets et participer aux scénarios. Je suis conscient du remarquable travail qui a été réalisé jusqu'à maintenant et ne prenez surtout pas cela pour une simple critique, mais je trouve :
- Que le moteur manque d'homogénéité dans son code source, manque de rigueur dans sa gestion des variables etc...
- manque de documentation

Par contre, il est indénibale qu'il y a tout un tas de fonctionalités géniales qui ont été greffées.
Alors, je me tate en ce moment : faire une version dérivée de Raydium avec l'accord des auteurs. Ou bien continuer sur ce qui a déjà été fait. Mais pour obtenir un code source clair et avec quelques normes de développement, y-a un gros boulot tout de même et si je ne suis pas suivi de près par les auteurs, je ne peux rien faire.

VOilà mon dilem. Actuellement, il n'y a pas de structure pour bosser à plusieurs sur le projet comme dans les autres projets OpenSource.

_________________
Life is Hard, and then you die.

Je vais parler sans savoir puisque (encore ...) je n'ai pas moyen de télécharger le document dont on parle ici. En revanche, il y'a effectivement une doc en anglais sur le Wiki, accessible depuis la première page du Wiki ou depuis le site de Raydium (API Reference Guide). Le problème d'écrire une doc à l'extérieur des sources, c'est sa maintenance. Je suis tout à fait d'accord pour proposer une version francaise de la doc de référence, mais il faut réfléchir à des solutions (très) simples pour qu'elle soit maintenue avec le moins de retard possible. Il ne faut pas perdre de vue que des fonctions et capacités s'ajoutent très régulièrement dans Raydium. Penser à d'autres langues possibles au passage serait idéal.

Pour le reste, je vais répondre mécaniquement point par point :
- documentation du volume : oubli réparé, merci.
- autres paramètres mal documentés : lequels ? Ces retours sont importants pour que la doc évolue. Raydium représente plus de 500 fonctions à l'heure actuelle, et tout documenter parfaitement du premier coup semble impossible pour un seul homme.
- liste des variables globales : vrai, cette liste manque. Mais la documentation présente le problème dans l'autre sens : les paragraphes d'introduction de chaque chapitre présentes les différentes variables globales du domaine concerné. Si le problème est de disposer d'un index de ces variables, il doit être possible de corriger le tir dans la doc intégrée et dans le script de génération (et donc sur le wiki).
- test6 n'est pas un petit test
- "manque d'homogénéité dans son code source, manque de rigueur dans sa gestion des variables" : intéressant. As-tu des explications plus précises de ça ? Pour quelles raisons refuserais-je de corriger ces problèmes si l'on m'en informe ? (je fais ici référence au possible fork dont tu parles)
- notre organisation : A l'origine, le projet n'avait même pas l'ambition de sortir de mon disque. Le forum est néé du besoin d'organiser les projets. Le wiki est arrivé pour les mêmes raisons ensuite, suite à la prise d'ampleur du moteur. En l'état actuel des choses, il manque (selon ma vision des choses) un système de gestion de versions, j'en ai déjà parlé. J'ai déjà exprimé mon souhait de mettre subversion en place pour résoudre ce problème, et j'ai aussi déjà exprimé mes difficultés d'accès à internet qui font que je ne suis absolument pas réactif en ce moment, sur l'ensemble de l'organisation et de la communication du projet.
Autre point, Raydium "n'appartient" à personne, le code est en GPL et je compte bien respecter tout ce que ça implique.

Merci pour ta réponse Xfennec.
je suis d'accord avec toi concernant la documentation à l'extérieur des sources. Il faudrait réaliser en effet une petite moulinette qui va chercher les informations dans le source par exemple, mais cela représente une souplesse en moins pour la rédaction du manuel.
Je ne sais pas trop comment évolue le moteur alors je ne saurais préconiser un système d'automatisation de la documentation. J'ai peur d'alourdir trop le code si on met ce genre de commentaire... remarque cela permettrait de savoir exactement qui fait quoi, quels sont précisément les paramètres en entrées, leurs bornes, les codes d'erreurs... Mais bon, cela signifie modifier tout le code. Et ça je voulais éviter puisqu'à l'heure actuelle, on ne sait pas trop comment bosser à plusieurs. Reste que si les fonctions évoluent, la compatibilité ascendante est toujours bonne comme tu me l'avais confirmé par mail, donc si la doc a un peu de retard, c'est peut-être pas si grave.
Il faudrait peser le pour et le contre... un débat en perspective. Et comme tu l'as bien dit, 500 fonctions à documenter, c'est énorme.

Tu parles du script de génération, peux-tu m'en dire d'avantage ? Serait-ce Doxygen ou un script équivalent que tu utilises ? Que permet-il ?

test6 est super, c'est pas ce que je voulais faire passer comme message. Tu l'as bien compris, mon but, c'est l'évolution du moteur et pas forcément son application.

"manque d'homogénéité dans son code source, manque de rigueur dans sa gestion des variables" : Oui, cela va du simple raydium_sound_verify à raydium_sound_VerifySources, problèmes de casse tout simple à des variables non documentées dont le type n'est pas explicite. Il est important d'établir des règles de codage, qui spécifieront une syntaxe précise et homogène pour diminuer le risque de bug et une meilleure lisibilité.
Voir http://www.gnu.org/prep/standards.html
L'identation du code ne semble pas respectée, mais c'est peut-être dû au passage vers windows. Utilises-tu GNU Indent ?
Encore une fois, je ne te blâme pas pour cela car y-a plein de projets que j'ai fait bille en tête et qui suivent les mêmes principes. Mais au bout d'un moment, si on veut rendre la solution péreine, surtout lorsqu'on bosse à plusieurs, il faut utiliser des règles d'encodage des variables, ... Mais l'approche objet est ici respectée. Cependant, par exemple, une variable globale ne se déclare jamais dans un include, mais seulement référencée de façon externe, puis déclarée dans le fichier .C qui l'utilise principalement.
Chaque fichier .C fait appel à tous les includes dont il a besoin mais pas plus. Cette solution du four-tout Common.H pose trop de problèmes pour l'édition de librairies et en plus on recompile presque tout dès qu'on le modifie. Globaliser oui, mais par fichier .C sinon on pourra pas bosser à plusieurs en même temps.

Mettre subversion en place pour résoudre ce problème : cela me semble une très bonne idée. Si je peux t'aider en quoi que ce soit, n'hésite pas à me demander.

En tous cas, ne t'y méprends pas : je suis admiratif du travail qui a été effectué. Je constate juste que tu as du quasiment tout faire seul, même si tu as été épaulé moralement par toute une équipe et je cela est très important. Je ne voudrais pas faire la mouche sur le gateau. C'est juste que de mon coté, j'ai hâte d'avancer là dessus, même si comme vous, ce n'est qu'un hobby car je développe des logiciels d'IA pour vivre. J'espère qu'on pourra faire un bout de chemin ensemble...

_________________
Life is Hard, and then you die.

J'insiste sur le fait que la documentation existe déjà en très grande partie, et dans le code source. le répetoire raydium/headers est composé des différentes entêtes, ou chaque domaine est documenté avec ses fonctions. De mémoire, seul la partie ODE n'est pas encore documentée (même si ça représente un gros morceau). Le script de génération de la documentation est placé dans le même répetoire, sous le nom raydoc.php et la doc générée est dispo ici : http://raydium.yoopla.org/wiki/RaydiumApiReference

Sur le reste du sujet, je suis tout à fait d'accord sur le fait que Raydium possède son propre "style" quand à son écriture, mélange de la naïveté des débuts et de l'expérience acquise par la suite. L'exemple de sound.c est à prendre à part, il a été codé par RyLe et intégré tel quel. L'ensemble des fonctions et des variables respectent des conventions de notation claires, et je ne pense pas le cas particulier de sound.c rende l'ensemble incohérent. Autre point, l'indentation du code est utilisée systématiquement suivant le style GNU tant qu'il ne gêne pas la lecture. Effectivement, sous Dev-Cpp, j'avais constaté que les tabulations n'étaient pas présentées de la même manière, une petite investigation peut être intéressante pour trouver un formatage qui convienne à un maximum d'éditeurs texte, pourquoi pas effectivement en regardant du coté d'indent. En revanche, je me refuse à utiliser la "notation polonaise" qui fait ressortir le type de la variable dans son nom. Bref, les conventions existent.

Je me suis déjà exprimé sur ce qui est maintenant le fichier common.h, en expliquant que si je devais le refaire maintenant, je ne procéderais pas de la même manière, mais que ce système avait aussi ses avantages (sur la vue globale du projet qu'il procure, par exemple). Je radote encore, mais je ne suis pas contre une ré-écriture de tout ça, mais ça ne me semble absolument pas être un problème en l'état actuel des choses. Je ne comprend pas par exemple en quoi c'est un problème pour l'édition de librairie (le .so se porte très bien, d'ailleurs). Si un autre système devait remplacer common.h, il est impératif qu'il ne nécessite pas un couple déclaration/définition pour chaque variable. Ce genre de démarche (pourtant déjà en place pour les fonctions) alourdi à mon sens considérablement l'évolution et la maintenance du tout. Il est important de ne jamais perdre de vue que Raydium vise la simplicité : c'est valable pour l'API qu'il propose mais aussi pour son mode de développement, et j'ose penser que c'est grace à cette sur-simplification que le projet en est arrivé là avec les moyens dont on dispose. Je n'ai aucun complexe par rapport à cette facon de travailler et je pense que ça se sait

Reste effectivement à voir comment SVN va être utilisé.

Bon, je pense que ça risque d'être difficile à bosser à plusieurs sur le moteur. Le projet est peut-être trop avancé...

Dans tous les cas, je dois étudier le travail déjà effectué et pour mes besoins, j'ai peut-être intérêt à développer une version alternative du moteur, pourquoi pas en C++. Je vais réfléchir à tout cela.

En attendant, bonne continuation à vous tous et encore bravo.

_________________
Life is Hard, and then you die.

Je suis désolé que ta conclusion soit celle ci. Sans chercher à imposer quoi que ce soit, je souhaite tout de même préciser que je n'ai jamais refusé le dialogue, et encore moins le travail de quelqu'un d'autre.

Ceci dit, merci pour ton travail sur le projet ainsi que pour tes compliments et encouragements, et j'espère sincérement te relire bientôt.

Oui bien sûr, je vais jeter un oeil régulièrement à l'avancée de vos travaux en vous souhaitant tous mes encouragements.

Pour l'instant, je test Ogre3D qui est peut-être plus adapté à ma recherche (uniquement l'affichage 3D et la dynamique, en C++ et prévu pour VS.NET).

_________________
Life is Hard, and then you die.