quesa-develop — Mailing list for Quesa development

Re: class registration/unregistration

[Roger H. <rog...@mi...>]

On Monday, January 31, 2005, at 06:43  pm, James W. Walker wrote:

> Did you test with Q3_MEMORY_DEBUG on?  For me, the block trailer test 
> in E3Memory_Free failed.

No I have never touched Q3_MEMORY_DEBUG unless it is turned on in the 
normal debugging version.



>>>  Before your changes, Quesa never used 
>>> kQ3XMethodTypeObjectClassRegister, correct?  Shouldn't it use 
>>> kQ3XMethodTypeObjectClassUnregister as well?
>>
>> Perhaps I should have invented a new name rather than use one I knew 
>> to be free and unlikely to be used.
>>
>> A new method is needed because I want to use constructors to fill in 
>> method pointers for each class's info
>> record and all its parent class info. This should work very well but 
>> there is the problem of what to do when
>> an external class is registered by an application/renderer. What is 
>> then needed is for each class to have a
>> method which will call call new(std::nothrow) for its own class to 
>> make the external class's info record and
>> fill in all the methods using the new class's meta-handler, its own 
>> meta handler and its ancestor class's
>> meta-handlers until it gets a non nil value returned (or it runs out 
>> of ancestors). The facility of adding new
>> method pointers for non built in classes is not something we are ever 
>> likely to allow (QD3D did not allow
>> it and up to now even built in classes could not do it, though I 
>> think built in QD3D classes probably did).
>> Anyway, as we are just setting up pointers to functions and not 
>> allocating memory then there is no need
>> to do anything similar on unregistering. Indeed if we were to need 
>> this we would need to have a virtual
>> destructor, and the use of virtual functions has been ruled out so 
>> this is a no-no.
>>
>> Shall I invent a new name? How about kQ3XMethodTypeNewClassInfo?
>
> Maybe I am misunderstanding, but are you saying that an external class 
> would need to call operator new?  I think it would be bad to make any 
> assumption about how an external class allocates memory.  A class 
> implemented in a plug-in may be built with a different compiler and 
> run-time library.

No when the external class registers itself in the normal way, Quesa 
now needs to call new for the parent class info (or the parent
of the parent class etc back as far as a built in class which has an 
operator new). Note this is the class INFO, not an instance.
The new method does just this, passing in a couple of parameters, the 
meta handler and the actual parent class.

> I think this discussion should be moved to the public list, in case 
> anyone else has ideas.

Done.



Roger.

P.S. have saved 40k on the size of the release version of Quesa just by 
optimising a couple of macros when
Q3DEBUG makes Q3ASSERT do nothing. In this condition we do not need to 
save a temporary boolean
to hold the result of the test. The compiler generates extra code to 
save and restore registers for the
temporary. This does not get optimised away under CW 8.3, maybe it 
would with other compilers but there
is no harm in the new version. I expect it saves some execution time 
too.

Re: exceptions (was Re: First stage of Quesa changes now complete)

[James W. W. <ja...@fr...>]

"Lane Roathe" <la...@if...> wrote:

>They have been advertising Mac OS X compatibility since about that time
>as well :) OK, since at least CW 7 was released ... and you pretty much
>have to have CW 9 to get true X compatibility. At least CW 8 only works
>about 50% in 10.2/10.3 for me.
>
>They also have had serious optimization bugs open since 1995 that have
>never been fixed.

I read the CodeWarrior groups on Usenet religiously, and I don't 
remember many recent complaints about optimizer bugs.  Most of the 
complaints seem to be about the IDE and debugger, not the compiler.

>(Not that any other compiler is any better, but just because they
>advertise something doesn't mean that they deliver it.)

Fair enough... and since I recently told Roger "test, don't hope", I 
did a quick test, kludging GLTextureManager.c and E3FFR_3DMF_Text.c 
so that they could be compiled with exceptions off.  I built the 
Carbon release CFM version of Quesa with and without exceptions.

Size: with exceptions, 1046K.  Without, 1003K.  About a 4% difference.

Speed: I ran the MultiBox test in Geom Test with both libraries.  If 
anything, it was a tad faster with exceptions, though I can't imagine 
why.  Let's just say the difference was probably within experimental 
error.
-- 
   James W. Walker, ScriptPerfection Enterprises, Inc.
   <http://www.write-brain.com/>

Re: exceptions (was Re: First stage of Quesa changes now complete)

[Lane R. <la...@if...>]

on Mon, Jan 31, 2005 James W. Walker may have said:

>There is some size overhead (whether it is "noticeable" is 
>subjective), but I don't think there is any speed overhead.  Since 
>1996 CodeWarrior has advertised "zero runtime overhead exception 
>handling".

They have been advertising Mac OS X compatibility since about that time
as well :) OK, since at least CW 7 was released ... and you pretty much
have to have CW 9 to get true X compatibility. At least CW 8 only works
about 50% in 10.2/10.3 for me.

They also have had serious optimization bugs open since 1995 that have
never been fixed.

(Not that any other compiler is any better, but just because they
advertise something doesn't mean that they deliver it.)

:)


Lane Roathe
President          Ideas From the Deep        <http://www.ifd.com>
___________________________________________________________________ 
If progress means moving forward, what does congress mean?

Re: exceptions (was Re: First stage of Quesa changes now complete)

[James W. W. <ja...@fr...>]

>>    That said, the Quesa source code does not currently contain any
>>explicit throw statements.  Hmm, I see that I did use one new
>>statement without nothrow, I guess I should fix that.  What happens
>>to a try/catch block if exceptions are off?
>
>I don't know -- one would hope it would cause a compile-time error.


So it does.  Well, that throws a monkey wrench in the works.  There 
are some try/catch blocks in GLTextureManager.c.  I could 
conditionalize them, but I don't know a portable way to test whether 
exceptions are turned on.


>>What compilers have a noticeable overhead for exceptions?  I don't
>>think either gcc or CodeWarrior fall into that category.
>
>CodeWarrior does, or at least did several years ago when I last
>looked into it.  It's possible things have changed since then.


There is some size overhead (whether it is "noticeable" is 
subjective), but I don't think there is any speed overhead.  Since 
1996 CodeWarrior has advertised "zero runtime overhead exception 
handling".
-- 
   James W. Walker, ScriptPerfection Enterprises, Inc.
   <http://www.write-brain.com/>

Re: exceptions (was Re: First stage of Quesa changes now complete)

[Joseph J. S. <jo...@st...>]

At 9:23 AM -0800 1/28/05, James W. Walker wrote:

>As I may have mentioned before, the STL was designed with the 
>expectation that exception support would be on.  I think it would be 
>a poor idea to build it with exceptions off.

I'm not a big fan of using STL, either, but I realize I'm not going 
to win that argument.

>   That said, the Quesa source code does not currently contain any 
>explicit throw statements.  Hmm, I see that I did use one new 
>statement without nothrow, I guess I should fix that.  What happens 
>to a try/catch block if exceptions are off?

I don't know -- one would hope it would cause a compile-time error.

>What compilers have a noticeable overhead for exceptions?  I don't 
>think either gcc or CodeWarrior fall into that category.

CodeWarrior does, or at least did several years ago when I last 
looked into it.  It's possible things have changed since then.

Best,
- Joe

-- 
,------------------------------------------------------------------.
|    Joseph J. Strout         Check out the Mac Web Directory:     |
|    jo...@st...           http://www.macwebdir.com/            |
`------------------------------------------------------------------'

Proposed new API CENameElement_PeekData

[James W. W. <ja...@wr...>]

I have found it useful to have a way to see the name of an object 
without the overhead of allocating and copying memory.  Would anyone 
object if I checked it in?

/*!
  *  @function
  *      CENameElement_PeekData
  *  @discussion
  *      Get the name element for an object.
  *
  *      The name parameter will receive a C string, or NULL if no name has
  *      been associated with the object. If a non-NULL pointer is returned,
  *      it should be considered read-only and temporary.  Unlike
  *	CENameElement_GetData, this function returns the actual string within
  *	the element, not a copy.
  *
  *	@availability			This function is not available in QD3D.
  *  @param object           The object to query.
  *  @param name             Receives the name associated with the object.
  *  @result                 Success or failure of the operation.
  */
#if QUESA_ALLOW_QD3D_EXTENSIONS

Q3_EXTERN_API_C ( TQ3Status  )
CENameElement_PeekData (
     TQ3Object                     object,
     const char                    **name
);

#endif // QUESA_ALLOW_QD3D_EXTENSIONS

-- 
   James W. Walker, ScriptPerfection Enterprises, Inc.
   <http://www.write-brain.com/>

Re: 1.6d20 release

[James W. W. <os...@jw...>]

On Jan 29, 2005, at 1:02 AM, Jose' Cruanyes wrote:

> well, if nobody objects, monday morning (CET time)  I'll upload the 
> packages on sourceforge,

OK.  Before that time, I will modify the release notes in the Mac and 
WIndows packages I made.

> after that we have to made a bit of publishing...

What do you mean?

> also I think we have to mark the release d20 on CVS

I didn't know it was possible to tag retroactively.
--
<http://www.jwwalker.com/>

Re: 1.6d20 release

[Frank C. <dev...@ch...>]

On 28-Jan-05, at 7:25 PM, James W. Walker wrote:

> If anyone observes that a change you're proud of is not explicitly 
> mentioned here, please assume that it was an oversight or laziness on 
> my part, not a deliberate slight.
>
> ** Changes from version 1.6d18 to 1.6d19:
>
> * Changed from LGPL to BSD license.
> * Improved window point picking of a Line geometry.
> * Implemented reading/writing of NURB patches.
> * Added Q3Bitmap_GetBit/Q3Bitmap_SetBit APIs.
> * Added functions Q3Object_GetProperty, Q3Object_RemoveProperty, 
> Q3Object_SetProperty.
> * Fixed automatic mipmapping.
> * Various bug fixes and optimizations.
> * Added cross-platform TGA texture reading to the Qut sample code.
> * Added an XCode project.

Couple more:

* Texture filters reworked to take advantage of mipmaps (QD3D parity 
and increased quality)
* Vertex colors modulated on textured geometry when using null shaders 
(QD3D parity)

> ** Changes from version 1.6d19 to 1.6d20:
>
> * Improved rendering of transparent geometries.
> * The OpenGL depth buffer is now 32 bits deep, as opposed to the 
> previous 16.

Might want to re-word that to "depth buffer now defaults to 32 bits 
deep" since it can still be changed, and might never actually reach 32 
bits on all hardware (my Geforce3 returns 24 bits when you request 32 
for example).

> * On Mac and Windows, the OpenGL context is not destroyed and 
> recreated when the window is resized.
> * On Mac and Windows, texture memory can be shared between draw 
> contexts.
> * Added a CodeWarrior project to build Quesa as a Mach-O framework.
> * Various bug fixes and optimizations.

I haven't played with Quesa much recently but things are looking good. 
I'm glad to see this release coming, as well as the major overhaul in 
progress.

Frank.
------------
<http://developer.chaoticbox.com>

Re: 1.6d20 release

[Jose' C. <cru...@ce...>]

well, if nobody objects, monday morning (CET time)  I'll upload the 
packages on sourceforge,
after that we have to made a bit of publishing...

And then we have to decide how to call the next release (1.7d1)? that 
should be released soon after

also I think we have to mark the release d20 on CVS


Il giorno 29/gen/05, alle 01:25, James W. Walker ha scritto:

> Jose' Cruanyes <cru...@ce...> wrote:
>
>> I've attached the ChangeLog from 1.6d18 to today, so if some volunteer
>> english native speaker can do the release note sfor d20
>
> Hmm, release notes, what a concept.  I don't find any release notes in 
> the 1.6d18 packages, so I don't have an example to imitate. Here's an 
> attempt.
>
> If anyone observes that a change you're proud of is not explicitly 
> mentioned here, please assume that it was an oversight or laziness on 
> my part, not a deliberate slight.
>
> ** Changes from version 1.6d18 to 1.6d19:
>
> * Changed from LGPL to BSD license.
> * Improved window point picking of a Line geometry.
> * Implemented reading/writing of NURB patches.
> * Added Q3Bitmap_GetBit/Q3Bitmap_SetBit APIs.
> * Added functions Q3Object_GetProperty, Q3Object_RemoveProperty, 
> Q3Object_SetProperty.
> * Fixed automatic mipmapping.
> * Various bug fixes and optimizations.
> * Added cross-platform TGA texture reading to the Qut sample code.
> * Added an XCode project.
>
> ** Changes from version 1.6d19 to 1.6d20:
>
> * Improved rendering of transparent geometries.
> * The OpenGL depth buffer is now 32 bits deep, as opposed to the 
> previous 16.
> * On Mac and Windows, the OpenGL context is not destroyed and 
> recreated when the window is resized.
> * On Mac and Windows, texture memory can be shared between draw 
> contexts.
> * Added a CodeWarrior project to build Quesa as a Mach-O framework.
> * Various bug fixes and optimizations.
> -- 
>   James W. Walker, ScriptPerfection Enterprises, Inc.
>   <http://www.write-brain.com/>


Pax et Bonum

# dott. Jose' Cruanyes Aguilar  -  C.E. Soft srl
#  Pzza. Firenze,4 MILANO  -  XX Settembre 10, CREMONA
#   02,33603122                0372,460602

Re: exceptions (was Re: First stage of Quesa changes now complete)

[James W. W. <ja...@wr...>]

I wrote:

>I've read a bunch of books to learn good C++ techniques, and I can't 
>remember any book suggesting that one not use exceptions.

Afterthought:  There is a piece of conventional wisdom that says 
"Pick an error handling strategy and stick to it."  Quesa has an 
established error handling strategy, which is to report errors by 
function result codes (usually kQ3Failure or NULL) and the 
error/warning/notice callbacks.  That's probably not what I would 
choose if I were designing a graphics engine from scratch today, but 
that's what we have.
-- 
   James W. Walker, ScriptPerfection Enterprises, Inc.
   <http://www.write-brain.com/>

Re: 1.6d20 release

[James W. W. <ja...@wr...>]

Jose' Cruanyes <cru...@ce...> wrote:

>I've attached the ChangeLog from 1.6d18 to today, so if some volunteer
>english native speaker can do the release note sfor d20

Hmm, release notes, what a concept.  I don't find any release notes 
in the 1.6d18 packages, so I don't have an example to imitate. 
Here's an attempt.

If anyone observes that a change you're proud of is not explicitly 
mentioned here, please assume that it was an oversight or laziness on 
my part, not a deliberate slight.

** Changes from version 1.6d18 to 1.6d19:

* Changed from LGPL to BSD license.
* Improved window point picking of a Line geometry.
* Implemented reading/writing of NURB patches.
* Added Q3Bitmap_GetBit/Q3Bitmap_SetBit APIs.
* Added functions Q3Object_GetProperty, Q3Object_RemoveProperty, 
Q3Object_SetProperty.
* Fixed automatic mipmapping.
* Various bug fixes and optimizations.
* Added cross-platform TGA texture reading to the Qut sample code.
* Added an XCode project.

** Changes from version 1.6d19 to 1.6d20:

* Improved rendering of transparent geometries.
* The OpenGL depth buffer is now 32 bits deep, as opposed to the previous 16.
* On Mac and Windows, the OpenGL context is not destroyed and 
recreated when the window is resized.
* On Mac and Windows, texture memory can be shared between draw contexts.
* Added a CodeWarrior project to build Quesa as a Mach-O framework.
* Various bug fixes and optimizations.
-- 
   James W. Walker, ScriptPerfection Enterprises, Inc.
   <http://www.write-brain.com/>

Re: First stage of Quesa changes now complete

[James W. W. <ja...@wr...>]

Roger Holmes <rog...@mi...> wrote:

>>  When Shark sees often-used square root operations, it suggests 
>>that if you don't need full precision, you can use a special 
>>PowerPC instruction, frsqrte, floating reciprocal square root 
>>estimate.  I don't know if we want to get into platform-dependent 
>>optimizations though.
>
>Do they suggest how to generate such code from a high level language ?

No.  I think the assumption is that if you're going to be optimizing 
at the machine instruction level, you should be willing to use 
assembly language.  However, CodeWarrior has "instrinsic functions", 
which basically allow you to use a machine instruction as if it were 
a C function call.
-- 
   James W. Walker, ScriptPerfection Enterprises, Inc.
   <http://www.write-brain.com/>

Re: First stage of Quesa changes now complete

[Joseph J. S. <jo...@st...>]

At 12:53 PM +0000 1/28/05, Roger Holmes wrote:

>>When Shark sees often-used square root operations, it suggests that 
>>if you don't need full precision, you can use a special PowerPC 
>>instruction, frsqrte, floating reciprocal square root estimate.  I 
>>don't know if we want to get into platform-dependent optimizations 
>>though.
>
>Do they suggest how to generate such code from a high level language ?

You use the inline assembly feature of the particular compiler you're 
using.  I agree with James -- I don't think we should get into this 
level of platform- (and compiler-) dependent optimizations yet.

Best,
- Joe

-- 
,------------------------------------------------------------------.
|    Joseph J. Strout         Check out the Mac Web Directory:     |
|    jo...@st...           http://www.macwebdir.com/            |
`------------------------------------------------------------------'

Re: exceptions (was Re: First stage of Quesa changes now complete)

[James W. W. <os...@jw...>]

On Jan 27, 2005, at 8:06 AM, Joseph J. Strout wrote:

> I hope I'm not (again) chiming in late here, but I hope we're building 
> Quesa (or at least, making it possible to build quesa) with exception 
> support turned off.  In at least some compilers, having exceptions on 
> incurs a noticeable overhead even if you're not using them.

As I may have mentioned before, the STL was designed with the 
expectation that exception support would be on.  I think it would be a 
poor idea to build it with exceptions off.  That said, the Quesa source 
code does not currently contain any explicit throw statements.  Hmm, I 
see that I did use one new statement without nothrow, I guess I should 
fix that.  What happens to a try/catch block if exceptions are off?

What compilers have a noticeable overhead for exceptions?  I don't 
think either gcc or CodeWarrior fall into that category.

> My experience also matches Dair's, i.e., that in C++ code, exceptions 
> tend to cause more grief than good.

I strongly disagree with that, if exceptions are used well.  It took a 
few years for people to learn how to use them well, e.g., how to write 
exception-safe code, so some early experience may have been negative.  
I've read a bunch of books to learn good C++ techniques, and I can't 
remember any book suggesting that one not use exceptions.
--
<http://www.jwwalker.com/>

Bug in E3Classtree.c?

[Jose' C. <cru...@ce...>]

at line 552 of E3Classtree.c there's an if statement finished in a 
semicolon
  seems a typo to me

Pax et Bonum

# dott. Jose' Cruanyes Aguilar  -  C.E. Soft srl
#  Pzza. Firenze,4 MILANO  -  XX Settembre 10, CREMONA
#   02,33603122                0372,460602

Re: exceptions (was Re: First stage of Quesa changes now complete)

[Roger H. <rog...@mi...>]

On Thursday, January 27, 2005, at 04:06  pm, Joseph J. Strout wrote:

>
> I hope I'm not (again) chiming in late here, but I hope we're building 
> Quesa (or at least, making it possible to build quesa) with exception 
> support turned off.  In at least some compilers, having exceptions on 
> incurs a noticeable overhead even if you're not using them.

That is our aim, I certainly have not written any throw statements and 
I am checking the list's collected wisdom
on anything contentious.



> My experience also matches Dair's, i.e., that in C++ code, exceptions 
> tend to cause more grief than good.

My experience is that exceptions have avoided writing reams of tests of 
status returns and freed up the
function result for the purpose it was intended for, the result of the 
function, and that being able to use
the function result rather than passing back through a star parameter 
both makes code simpler to
understand, more elegant and avoids undefined variables because I 
almost never have to write a
declaration without an initialiser.

Wouldn't life be boring if we all the same!

Roger.

Re: First stage of Quesa changes now complete

[Roger H. <rog...@mi...>]

On Wednesday, January 26, 2005, at 07:44  pm, James W. Walker wrote:

> Roger Holmes <rog...@mi...> wrote:
>
>> 9.7% of the time in sqrt. I have switched my renderer to use 
>> std::sqrtf as
>> it only ever handle floats, never doubles. Hopefully will speed 
>> things up.
>
> Here's a quote from a recent thread on Apple's performance 
> optimization mailing list:
>
> At 4:44 PM +0000 1/23/05, Jerry wrote:
>>>>  This should be faster, since it need compute fewer
>>>>  bits of precision, but it is still returning the correct result,
>>>>  rounded to a float.
>>>
>>>  On some architectures. On others the calculations will be in double
>>>  precision and shortened to float on return.
>>
>> This is exactly what libmx does on OS X (try stepping into it in the 
>> debugger), so switching to the "f" functions may actually slow you 
>> down.
>
> Moral:  Don't just hope, test.

Later on I did, and the times were identical.

>
> When Shark sees often-used square root operations, it suggests that if 
> you don't need full precision, you can use a special PowerPC 
> instruction, frsqrte, floating reciprocal square root estimate.  I 
> don't know if we want to get into platform-dependent optimizations 
> though.

Do they suggest how to generate such code from a high level language ?

>
>> I think in the release version we are checking out inputs too often, 
>> for instance
>> in E3Shared_Acquire we check the parameter is of type shared. We then 
>> call
>> Q3Shared_GetReference which again checks its parameter is of type 
>> shared.
>> It also calls E3System_Bottleneck even though we must have come into
>> E3Shared_Acquire from a Q3 routine which will have already called
>> E3System_Bottleneck.
>>
>> My question is this, can I change the call to Q3Shared_GetReference 
>> into a
>> call of E3Shared::GetReference (my preferred option) or can I remove 
>> the
>> check in E3Shared_Acquire  or should I leave it alone?
>
> It's OK with me if you change the Q3Shared_GetReference to 
> E3Shared::GetReference.
>
> As long as you're messing with E3Shared_Acquire, how about combining 
> the two if (theObject != NULL) statements into one?

Done.

>
>> Can I apply you answer to all similar situations or should I ask 
>> every time?
>
> You may apply my answer in similar situations.


Thanks.

Re: First stage of Quesa changes now complete

[Roger H. <rog...@mi...>]

On Thursday, January 27, 2005, at 04:10  pm, Joseph J. Strout wrote:

>
> That is surprising.  This may be a silly question, but are you sure 
> Sampler is showing you the time spent only in the parent function, and 
> not the time spent in the parent function or any of its children 
> (functions it calls)?

Yes, you have to check the box 'Invert call tree' , then the left hand 
column displays just the time in a each function.
We call Q3Object_Is_Type from nearly every Q3 routine and some of the 
E3 routines too.

>
>> I think in the release version we are checking out inputs too often, 
>> for instance in E3Shared_Acquire we check the parameter is of type 
>> shared. We then call Q3Shared_GetReference which again checks its 
>> parameter is of type shared.
>> It also calls E3System_Bottleneck even though we must have come into
>> E3Shared_Acquire from a Q3 routine which will have already called
>> E3System_Bottleneck.
>
> That's a good point.  I would think that once we're in a E3 routine, 
> we should be safe to directly call another E3 routine rather than 
> going through the Q3 version.  As a general principle, we may trust 
> ourselves, even if we don't trust the user.

Good. I'm not going to do a wholesale change, but when I find a time 
critical area I will apply that principal.
As for not trusting the user, in a debugging environment I agree 
wholeheartedly, in production if we detect
an error then most of the time an application will merely fail in 
another way. I use Quesa through C++ wrappers
so that I would actually have to go out of my way to call Quesa with an 
object parameter which was not
actually an object. Maybe I could compile a special version of Quesa 
where Q3Require etc are defined to be
nothing, just like Q3Debug is in the release version.

Roger.

Re: inlining (was Re: First stage of Quesa changes now complete)

[James W. W. <os...@jw...>]

On Jan 27, 2005, at 8:11 AM, Joseph J. Strout wrote:

> At 10:07 PM +0100 1/26/05, Jose' Cruanyes wrote:
>
>>> a single line function (OpaqueTQ3Object::IsObjectValid) into
>>> an inline in the class definition. Is it OK to check this in or is
>>> there a policy against in-lines?
>>
>> nothing against if not exposed in the Quesa headers
>
> But how can you make an inline function without exposing it in the=20
> headers?

I'd guess that Jos=E9 probably meant that inline functions should not be=20=

in the *public* headers.
--
<http://www.jwwalker.com/>

HeaderDoc updated

[James W. W. <ja...@wr...>]

Since I couldn't get Quesa's HeaderDoc to work right, I replaced 
Dair's customized version with a newer standard version (7.4.8).

If you use Mac CVS Pro, I suggest that before you check out these 
files, you open your Mac CVS Pro session settings, and set the 
extensions .pl, pm, and .config to be text with Unix line endings.

To generate headers with the terminal in Mac OS X, the steps are:
1. cd into the Scripts/HeaderDoc directory.
2. perl headerDoc2HTML.pl -o ../../../Documentation/developer/apiref 
../../../SDK/Includes
3. perl gatherHeaderDoc.pl ../../../Documentation/developer/apiref

The Perl script DoQuesaDocs.pl was apparently supposed to automate 
these steps, but it it skipping the last step and I don't know why.
-- 
   James W. Walker, ScriptPerfection Enterprises, Inc.
   <http://www.write-brain.com/>

Re: 1.6d20 release

[James W. W. <ja...@wr...>]

"Joseph J. Strout" <jo...@st...> wrote:

>Not me -- I haven't used perl in years, and when I did use it, it
>was very briefly and with great distaste.  ;)  Dair is normally very
>good about commenting, though; is there nothing inside the file to
>indicate its use?
>
>If necessary, I could write a new app to generate the docs from the
>headers.  But it'd probably be quicker to get the perl script
>running again.

I made some progress.  All the files in Scripts/HeaderDoc need to 
have Unix line ends rather than Macintosh line ends.  With that 
change, I got something to happen, but the output is wrong.  I wonder 
if this version of HeaderDoc is incompatible with the version of perl 
in Mac OS X.  The next step will be to download a newer HeaderDoc. 
(But not version 8.0, which I already know to be incompatible with 
the Q3_EXTERN_API_C macros in the Quesa headers.)
-- 
   James W. Walker, ScriptPerfection Enterprises, Inc.
   <http://www.write-brain.com/>

Re: 1.6d20 release

[Joseph J. S. <jo...@st...>]

At 10:54 PM -0800 1/26/05, James W. Walker wrote:

>I made drafts of the SDKs:
>
><ftp://ftp.frameforge3d.com/misc/quesa_1.6d20_sdk_win32.zip>
>
><ftp://ftp.frameforge3d.com/misc/quesa_1.6d20_sdk_mac.sit>

Thank you, James!  I had intended to do the Mac one, but I'm happy to 
see that you have beaten me to it.

I'll give it a try later today and let you know if anything seems amiss.

>As for the source releases, I suppose we should regenerate the API 
>reference from the headers.  I tried running the DoQuesaDocs.pl 
>script, and nothing happened.  No error message, no docs.  Anyone 
>know how this is supposed to work?

Not me -- I haven't used perl in years, and when I did use it, it was 
very briefly and with great distaste.  ;)  Dair is normally very good 
about commenting, though; is there nothing inside the file to 
indicate its use?

If necessary, I could write a new app to generate the docs from the 
headers.  But it'd probably be quicker to get the perl script running 
again.

Best,
- Joe

-- 
,------------------------------------------------------------------.
|    Joseph J. Strout         Check out the Mac Web Directory:     |
|    jo...@st...           http://www.macwebdir.com/            |
`------------------------------------------------------------------'

inlining (was Re: First stage of Quesa changes now complete)

[Joseph J. S. <jo...@st...>]

At 10:07 PM +0100 1/26/05, Jose' Cruanyes wrote:

>>a single line function (OpaqueTQ3Object::IsObjectValid) into
>>an inline in the class definition. Is it OK to check this in or is
>>there a policy against in-lines?
>
>nothing against if not exposed in the Quesa headers

But how can you make an inline function without exposing it in the headers?

-- 
,------------------------------------------------------------------.
|    Joseph J. Strout         Check out the Mac Web Directory:     |
|    jo...@st...           http://www.macwebdir.com/            |
`------------------------------------------------------------------'

Re: First stage of Quesa changes now complete

[Joseph J. S. <jo...@st...>]

At 6:59 PM +0000 1/26/05, Roger Holmes wrote:

>Secondly I have been running the old 'Sampler' tool on our application
>while it is refreshing the screen using the Microspot Renderer which of
>course uses Quesa.

I haven't used Sampler in a long time, but...

>6.2% in Q3Object_IsType
>...
>3.0% in E3Object_IsType, so actually doing the work is quicker than
>Q3Object_IsType  the glue routine above which checks parameters and calls us!

That is surprising.  This may be a silly question, but are you sure 
Sampler is showing you the time spent only in the parent function, 
and not the time spent in the parent function or any of its children 
(functions it calls)?

>I think in the release version we are checking out inputs too often, 
>for instance in E3Shared_Acquire we check the parameter is of type 
>shared. We then call Q3Shared_GetReference which again checks its 
>parameter is of type shared.
>It also calls E3System_Bottleneck even though we must have come into
>E3Shared_Acquire from a Q3 routine which will have already called
>E3System_Bottleneck.

That's a good point.  I would think that once we're in a E3 routine, 
we should be safe to directly call another E3 routine rather than 
going through the Q3 version.  As a general principle, we may trust 
ourselves, even if we don't trust the user.

-- 
,------------------------------------------------------------------.
|    Joseph J. Strout         Check out the Mac Web Directory:     |
|    jo...@st...           http://www.macwebdir.com/            |
`------------------------------------------------------------------'

exceptions (was Re: First stage of Quesa changes now complete)

[Joseph J. S. <jo...@st...>]

At 8:51 AM -0800 1/26/05, James W. Walker wrote:

>Unless you have a strategy for dealing with exceptions, and catching 
>them before they try to escape from the library, then use 
>new(std::nothrow), which is one of the standard versions of operator 
>new.

I hope I'm not (again) chiming in late here, but I hope we're 
building Quesa (or at least, making it possible to build quesa) with 
exception support turned off.  In at least some compilers, having 
exceptions on incurs a noticeable overhead even if you're not using 
them.

My experience also matches Dair's, i.e., that in C++ code, exceptions 
tend to cause more grief than good.

Best,
- Joe

-- 
,------------------------------------------------------------------.
|    Joseph J. Strout         Check out the Mac Web Directory:     |
|    jo...@st...           http://www.macwebdir.com/            |
`------------------------------------------------------------------'