Crystal Space 3D SDK

On Sun, 29 Oct 2000 13:20:30 +0100, Martin Geisse wrote:

>To see if I have understood everything you want the sound system to do,
>here's the structure so far (without effect processors yet). To play sounds,
>you have to:
>- load the sound completely or streamed; either way you get an iSoundData.
>no preparation is done at this time.
Exactly. Moreover, for some specific applications (for example, speech) you may 
create a object that implements the iSoundData interface, and generates the data 
stream at runtime.

>- create any number of sound sources. Now any format conversion, transfer to
>soundcard RAM etc. is done.
By the way, about sound format descriptor. We could fit in a single integer 
everything we need, e.g. sound format (8/ 16 bits or "don't care" - two bits for 
this), signed vs unsigned vs don't care (another two bits) the rate (say 16 
bits) ... umm, what else?

Now the iSoundData could have a SetFormat() method which will change the sound 
data to given format (same as for iImage's).

>Internally this creates a iSoundStream from the sound data to read the samples.
Do we need a separate iSoundStream? I don't like having too much interfaces, 
whats the exact need for separate iSoundData and iSoundStream? Can't we use just 
one (iSoundStream sounds better).

>Streamed and non-streamed sounds act the same way here apart from the fact
>that you may create only one sound source from a streamed sound.
Exactly. In fact, you should be prepare for a error code to be returned from 
CreateSource() in any case - not just for the fact that a dynamic stream is 
already in use. This is up to iSoundStream to decide whenever it wish or doesn't 
wish to have several iSoundSource's created from it. We could use a mechanism 
similar to IncRef/DecRef for this.

>If you use csEngine, you will also use csSoundWrapper, which is a csObject
>wrapper for iSoundData.
csSoundWrapper should be a placeholder which will contain just the name of the 
file and such. As soon as the sound drivers are loaded, csSoundWrapper will 
create the respective iSoundStream's.

>Disadvatages:
>- only one source from the same *streamed* sound
>- On systems that copy the sound into soundcard RAM, the sound is copied
>again and again for every sound source.
This is up to the driver. It can identify the sound even by the iSoundStream 
pointer, and keep a list of loaded sounds; if the corresponding iSoundStream has 
already been loaded into on-board RAM, it just re-uses the same sound (and does 
another IncRef on the corresponding iSoundStream).

This is even a must if the iSoundStream will be freed by calling something like 
iSoundStream::FreeData() after loading it into on-board RAM (to conserve RAM).

Greetings,
    _\ndy@...

On Sun, 29 Oct 2000 13:20:30 +0100, Martin Geisse wrote:

>- On systems that copy the sound into soundcard RAM, the sound is copied
>again and again for every sound source.
Another thought: maybe we can emulate on-board RAM on all APIs, even those that 
don't support it?

Greetings,
    _\ndy@...

> I would agree that we need this.  In addition it would be smart to have
> more documentation on each class.  It takes a good bit of time trying to
> figure out everything that is going on inside each member.  What would
> be helpful is to document (in a seperate file not just commenting in the
> code) why things were done the way they were.     

I agree that a better documentation of classes would be nice (the
hierarchical listing is pretty good already but ...). If whoever is in
charge of the API documentation could contact me, maybe we could set up
some way to get that started. Of course the problem I see is that all the
real information is with the programmers and they know and would much
rather be programming. 

I could, if there is enough interest (i.e. anough ANSWERS), set up
something like what php.net has: the API docs with user comments for each
page (a little database back end, php interface for searching and
posting). And maybe that sort of thing could ultimately be hosted at the
sourceforge? 

> For example, I'm currently getting the infinite renderer to work in
> MSVC.  Infinite doesn't create a canvas. Infinite will not work under
> Windows if a window isn't created and my concern is that when I add the
> canvas it could cause problems on other platforms.  It would be nice to
> know why it wasn't included in the first place.  A documentation file
> with this info could save time and potential cross-platform problems.      

Could ... but maybe just posting that info to the mailing list would be
better. After all there is an archive of that list and the point of
documantation is EASY access. I don't want to read the whole xx megabayte
of documentation. I just want to start DOING.
 
> I know I'm spending a lot of time learning what's going on and I'm sure
> others are doing the same thing.  If we could decrease the learning
> time, then more time could be spent adding to the project instead of
> figuring out how to work with specifics in the project.    

Yes ... it would be nice if there were a short commentary about the
develoment etiquette, who's doing what, how to contribute, what not to
touch etc. I assume if I hang around long enough I may find out just by
assimilation ... but I might not have the perseverance!

> There's a pretty good article on gamedev.net on commenting and
> documenting. Check it out at
> http://www.gamedev.net/reference/programming/features/codedoc/     

Cool article!

Rudolf

rdscrystalspace@... wrote:

> For example, I'm currently getting the infinite renderer to work in MSVC.  Infinite doesn't create a canvas. Infinite will not work under Windows if a window isn't created and my concern is that when I add the canvas it could cause problems on other platforms.  It would be nice to know why it wasn't included in the first place.  A documentation file with this info could save time and potential cross-platform problems.

I can answer this question. Infinite was written as a renderer to do performancetesting. It actually doesn't really render anything so that's why it doesn't need
a canvas. If you run CS with the infinite renderer then you basicly are
treating CS as a console program.Greetings,

Rudolf Potucek wrote:

>I could, if there is enough interest (i.e. anough ANSWERS), set up
>something like what php.net has: the API docs with user comments for each
>page (a little database back end, php interface for searching and
>posting). And maybe that sort of thing could ultimately be hosted at the
>sourceforge? 

I looked at what they have there and it's not a bad idea.  The only thing I saw that I didn't like was that you had to wade through questions and comments about questions (not answers) to find information.

I think a good balence would be to have a similar system as php.net but have it to post information ONLY.  No questions or requests, we can still use the mailing list for that.  

The original programmer would post the internal documentation when the code is summitted to CVS.  If any additional questions are raised later the answers could be posted to the internal documentation, preferably by the one who raised the question.  Also when changes are made to the code, the new information about the code would be posted by the author to the internal documenation.

>Could ... but maybe just posting that info to the mailing list would be
>better. After all there is an archive of that list and the point of
>documantation is EASY access. I don't want to read the whole xx megabayte
>of documentation. I just want to start DOING.

The problem with posting just to the mailing list is that it can be more dificult to get the info you want.  If you go to look in the archives, it can take ALOT of time to sort through all of the information that has been posted.

Also, if you post a question about what you are currently working on, there is a chance (in the case of wanting class information) that the programmer will not remember exactly why it was implimented that way.  Also, it takes away from the programmer's current task to rehash was was done months ago.  

BTW, you can find some class information by looking at the CVS repository.

>Yes ... it would be nice if there were a short commentary about the
>develoment etiquette, who's doing what, how to contribute, what not to
>touch etc. I assume if I hang around long enough I may find out just by
>assimilation ... but I might not have the perseverance!

You can find some coding and development etiquette in the docs.  But as far as knowing who is doing what, I'm not sure how this works out either.  

Richard D Shank 
__________________________________________________________________
Make A Buck Or Two @ TheMail.com - Free Internet Email
Sign-up today at http://www.themail.com/ref.htm?ref=898251

> I looked at what they have there and it's not a bad idea.  The only
> thing I saw that I didn't like was that you had to wade through
> questions and comments about questions (not answers) to find
> information. 
>
> I think a good balence would be to have a similar system as php.net but
> have it to post information ONLY.  No questions or requests, we can
> still use the mailing list for that.  

I agree ... but that's hard to do because it would mean reading EVERY
incoming post. I'd probably limit it to about 10 posts to each page and
then do a manual weedout/integration.

> The original programmer would post the internal documentation when the
> code is summitted to CVS.  If any additional questions are raised later
> the answers could be posted to the internal documentation, preferably by
> the one who raised the question.  Also when changes are made to the
> code, the new information about the code would be posted by the author
> to the internal documenation.

This would be neat ... YOU tell the programmers ;)

Rudolf

Rudolf Potucek wrote:

> > I would agree that we need this.  In addition it would be smart to have
> > more documentation on each class.  It takes a good bit of time trying to
> > figure out everything that is going on inside each member.  What would
> > be helpful is to document (in a seperate file not just commenting in the
> > code) why things were done the way they were.
>
> I agree that a better documentation of classes would be nice (the
> hierarchical listing is pretty good already but ...). If whoever is in
> charge of the API documentation could contact me, maybe we could set up
> some way to get that started. Of course the problem I see is that all the
> real information is with the programmers and they know and would much
> rather be programming.

I'm not in favor of this. The API documentation as we are doing it now
is the best approach IMHO. The problem with seperate API documentation
is that the API is still too volatile at the moment and there is the VERY BIG
risk of the documentation getting outdated. Now the API documentation
is included with the header files which makes it much less likely that it
will get outdated.

Also the output from Doxygen is very nice IMHO. I really see no need
for yet another API reference. The one we have is good enough.

However, we need more tutorials and more user docs.


> Yes ... it would be nice if there were a short commentary about the
> develoment etiquette, who's doing what, how to contribute, what not to
> touch etc. I assume if I hang around long enough I may find out just by
> assimilation ... but I might not have the perseverance!

Some of that stuff is in the CS docs. Did you actually browse the CS
docs? There is a lot of what you want already in there.

Greetings,


--
==============================================================================
Jorrit.Tyberghein@..., University Hospitals KU Leuven BELGIUM

They drove back through the dawn, while the cassette player played J. S.
Bach's Mass in B Minor, vocals by F. Mercury.
        -- (Terry Pratchett & Neil Gaiman, Good Omens)
==============================================================================

rdscrystalspace@... wrote:

> Unless I am just confused, I belive even a console under Windows has to have a window.

Yes, but only a console window for text output. I don't know windows very well but
how do the other CS applications run that have no graphics window? i.e. like 'vsh'
and 'scfreg'?

Greetings,


--
==============================================================================
Jorrit.Tyberghein@..., University Hospitals KU Leuven BELGIUM

They drove back through the dawn, while the cassette player played J. S.
Bach's Mass in B Minor, vocals by F. Mercury.
        -- (Terry Pratchett & Neil Gaiman, Good Omens)
==============================================================================

Hmm ... this routine draws a pixel at position x, y ... seems like your =
map is somehow messed up, can't explain why you should get such an error =
...?!
  ----- Original Message -----=20
  From: Patrick Flanagan=20
  To: crystal-main@...
  Sent: Sunday, October 29, 2000 9:58 PM
  Subject: [CsMain] question about a map


  I have a map that I made that I am trying to convert to Crystal Space =
format. When I run map2cs on the .map file, it works fine and generates =
a zip file containing the world. However, when I try to run walktest =
with my map it goes through the normal startup stuff, but when it gets =
to=20

  Initializing lightmaps <2 sectors> :
      ... 100%
  Shining lights <11 lights> :
  0% ..

  At the very beginning of the shining lights part, it stops and gives =
the following error :=20
  Fatal error - Array bound error in file d:\crystal =
space\cs\libs\csengine\polygon\polytext.cpp, line 538.

  So I checked this file, line 538, and it's part of this function :

  static void __sub_PutPixel (int x, int y, float area, void *arg)
  {
    csCoverageMatrix *cm =3D (csCoverageMatrix *)arg;
    if (x >=3D cm->width || y >=3D cm->height || x < 0 || y < 0)
    {
  #ifdef CS_DEBUG
      CsPrintf(MSG_INTERNAL_ERROR, "Array bound error in file %s, line =
%d\n",
        __FILE__, __LINE__);
  #endif
      return;
    }
    cm->coverage [cm->width * y + x] -=3D area;
  }

  I'm not familiar with what this function does. What might be the =
trouble with the map, or what could I do to fix it? Thanks in advance.
  =20
  Patrick

Upon further investigating, I found that it also crashes when in the DrawBox function in graph2d.  Maybe this is what is calling the pixel drawing routine? Like I said, I'm not familiar with the engine part, so any help is appreciated. Thanks in advance


  ----- Original Message ----- 
  From: Tristan McLure 
  To: crystal-main@... 
  Sent: Sunday, October 29, 2000 5:27 PM
  Subject: Re: [CsMain] question about a map


  Hmm ... this routine draws a pixel at position x, y ... seems like your map is somehow messed up, can't explain why you should get such an error ...?!
    ----- Original Message ----- 
    From: Patrick Flanagan 
    To: crystal-main@... 
    Sent: Sunday, October 29, 2000 9:58 PM
    Subject: [CsMain] question about a map


    I have a map that I made that I am trying to convert to Crystal Space format. When I run map2cs on the .map file, it works fine and generates a zip file containing the world. However, when I try to run walktest with my map it goes through the normal startup stuff, but when it gets to 

    Initializing lightmaps <2 sectors> :
        ... 100%
    Shining lights <11 lights> :
    0% ..

    At the very beginning of the shining lights part, it stops and gives the following error : 
    Fatal error - Array bound error in file d:\crystal space\cs\libs\csengine\polygon\polytext.cpp, line 538.

    So I checked this file, line 538, and it's part of this function :

    static void __sub_PutPixel (int x, int y, float area, void *arg)
    {
      csCoverageMatrix *cm = (csCoverageMatrix *)arg;
      if (x >= cm->width || y >= cm->height || x < 0 || y < 0)
      {
    #ifdef CS_DEBUG
        CsPrintf(MSG_INTERNAL_ERROR, "Array bound error in file %s, line %d\n",
          __FILE__, __LINE__);
    #endif
        return;
      }
      cm->coverage [cm->width * y + x] -= area;
    }

    I'm not familiar with what this function does. What might be the trouble with the map, or what could I do to fix it? Thanks in advance.
     
    Patrick

Constantine Elster wrote:

>
> Hi. What's csRadiosity and how to use it?

csRadiosity is the class that controlls radiosity in CS. It works
mostlybut there is still a small problem with it. Sometimes colors just
explode.
You normally don't use this class yourselves. It is mostly meant
as a private class for the engine which is used when the engine
calculates
radiosity. You can enable radiosity by editing data/config/cryst.cfg
and setting Radiosity=yes. It takes a LONG time to calculate though
and there are some bugs still...

Greetings,

>Alright.  Maybe we can take the current FAQ (only on the website I think)
and break it up into subsections and include this kind of stuff.


This FAQ is part of the docs: cs/docs/texinfo/appendix/faq.txi

Martin Geisse

On 28 Oct 2000, Ed Page wrote:

> > Q: What is a sprite? How is it different from just taking a csThing and
> >    moving it around (like in blocks app)?
> > A:
> Sprites and things are designed for different tasks.  Things are
> designed for static objects while sprites are what are more common in
> other apps where we see there are animated models.  So sprites are key
> framed and skeletally animated while things just sit there.

The last sentence should be more like:

"Sprites can be vertex animated or skeletally animated, while things are
not animated."

The phrase "key framed" is confusing (either inaccurate or redundant
depending on whether you interpret it as meaning "vertex animated" or as a
part of "skeletally animated")

Things don't change shape, but they can move, they don't necessarily "just
sit there" - some of them are actually quite active :-)

> > Q: The simple app and tutorial load a sprite template from disk. So I
> >    looked and that file looks like some sort of VRML file or whatever.
> >    Where did that come from? Can I make those somehow?
> > A:
> Right now conertors from other games are used to make sprites.  You
> can make your own sprite from hand, or in a modeler for a supported
> format like Quake's mdl or Quake 2's mdl2.

This answer should probably have links to pages that describe the sprite
template format and specific convertors.

There are actually three approaches:

1. create the sprite template by hand
2. use a convertor program
3. some formats can be loaded directly (mdl, md2, what others?)
  __    __    _                                    _    __    __
_/  \__/  \__/  Seth Galbraith  "The Serpent Lord"  \__/  \__/  \_
 \__/  \__/  \_ sgalbrai@...  #2244199 on ICQ  _/  \__/  \__/
_/  \__/  \__/    http://www.planetquake.com/gg     \__/  \__/  \_

On Sunday 29 October 2000 00:39 Rudolf Potucek wrote:
>Hi Everyone!
>
>Supposedly there is a doc file helping to make the transition from 0.16 to
>0.17 but I can't seem to find it in either 17r001 or 17r002. (downloaded
>the bz2 files from sourceforge). Where is it or what is it called?
>
>Rudolf
>

it should be in CS/docs/texinfo/appendix/apimod17.txi.
dont know if its converted to html.

norman

VERY good idea. I have no time to answer the questions now but I'll
do so on monday.

Greetings,

Rudolf Potucek wrote:

> Hi Everyone!
>
> Ok, I am out of the big stress phase, so I have now had the time to take a
> deeper look at CS ... and I am still not sure how everything interacts.
> And how am I going to use CS, if the only way to find out is trial
> and error (mainly learning from seg-faults)? Because of that, and because
> I think I am not the only one starting with this problem, I would like to
> start a FAQ (unless there is one ... no, the tutorial is great but no
> help in getting started) on the most common startup questions.
>
> And to make a start, I will phrase some questions, which I hope someone
> can answer (even just briefly, I am willing to do the legwork and figure
> out what it means ;) I have also supplied some answers ... as best I know.
> I am sure there are many more questions and answers, so hit me with them
> or point me to the FAQ I missed.

Wow!

Thanks for all the positive feedback! I have posted a current version of
the FAQ (in it's current stated) at http://cs-faq.gobbledigook.dhs.org/ 

Whenever this reaches general consent we'd need to include it into the CS
distribution at SourceForge, but I have no clue how to do that. And
speaking of Sourceforge, I noticed that there wa no entry in the 'Doc'
section of CS ... shouldn't the tutorial etc. be linked in there?

Rudolf