Huge API change (fwd)

SDL Development
1

[NOTE: I’m not sending this to Dave Ashley or the SDL list, only to you]

Two people want to influence the design of an architecture.

One is clearly concerned with errors always being accurately reported.

The other says thing like

"... he/she can copy the structure to some safe area after each
 function call"

and demonstrates a lack of understanding of re-entrancy and

"... I don't see myself using this elaborate error stuff anyway. I
 mean, the SDL function calls I am using can't generate some
 unexpected error, can they? For example if I call SDL_UpdateRect,
 what all can go wrong if my coords are within the window?"

demonstrating a lack of concern for errors in general.

Knowing nothing other than the above information about the two
individuals, to whom would you turn to for advice?

Now I’m guessing you sent me Dave’s email because you agree with me,
but you don’t know how to tell Dave this. My question above doesn’t
really help you, but perhaps you can say something like “Over the
years I’ve come to trust Cliff’s judgement.”

–Cliff
@Clifford_T_Matthews
Status: R

Received: from [17.254.0.52] (helo=mail-out1.apple.com)
by roboto.devolution.com with esmtp (Exim 3.01 #1)
id 119M15-0005sc-00
for slouken at devolution.com; Tue, 27 Jul 1999 22:12:35 -0700
Received: from mailgate2.apple.com ([17.129.100.225])
by mail-out1.apple.com (8.8.5/8.8.5) with ESMTP id WAA47062
for ; Tue, 27 Jul 1999 22:13:58 -0700
Received: from scv3.apple.com (scv3.apple.com) by mailgate2.apple.com
(Content Technologies SMTPRS 2.0.15) with ESMTP id for ;
Tue, 27 Jul 1999 22:13:48 -0700
Received: from woapp2 (woapp2.apple.com [17.128.100.182])
by scv3.apple.com (8.9.3/8.9.3) with SMTP id WAA19106
for slouken at devolution.com; Tue, 27 Jul 1999 22:13:46 -0700
Message-Id: <199907280513.WAA19106 at scv3.apple.com>
Status: R

Thank you for your purchase – you are now moments away from harnessing
the power of QuickTime Pro. To enter the next level of multimedia
functionality, use the key(s) listed below to unlock the advanced
features of QuickTime Pro. (You should print this message and save it
as a record of your purchase.)

KEY AND INSTALLATION INSTRUCTIONS

Name: Sam Lantinga

QuickTime Pro Key(s) for Mac OS

C9D5-95A4-05E1-7BA6-7D82

Installation Instructions for Mac OS

To unlock the features of QuickTime Pro, enter your name and
QuickTime Pro key in the QuickTime Settings Control Panel (this panel
will only be available if you’ve already installed QuickTime ). Open
your QuickTime Settings Control Panel, choose Registration from the
pop-up menu, and enter your name and key exactly as they appear on this
page. Make sure you don’t enter any additional characters or spaces.
Please note that QuickTime Pro keys consist of five groups of four
characters separated by dashes, like this: 6F12-D9B6-4S3B-J2EF-6ACC

INVOICE

Sam Lantinga
23149 Los Alisos Blvd #202
Mission Viejo, CA 92691
US

Card Number: xxxxxxxxxxxx7914
Transaction ID: 157657
Transaction Date: July 27, 1999

Quantity Item description Unit Cost Total Cost

1 29.99 $29.99
QuickTime Pro for Mac OSFrom: order-bot@apple.com
Date: Tue, 27 Jul 1999 22:13:46 -0700
Subject: Confirmation of QuickTime 4 Pro Upgrade
To: slouken at devolution.com
----------
TOTAL $29.99

TERMS OF SALE

Use of Key(s)
The buyer acknowledges that the right to use the key(s) issued above is
personal to the buyer or the organization the buyer represents, that the
buyer or such organization will use each key only to upgrade a single
copy of QuickTime for which the buyer or such organization has a valid
license, and that neither the buyer nor such organization may
redistribute the key(s) or allow anyone else to use it or them.

Title & Delivery
Title on all digital transactions passes to purchaser at Apple’s web site
in California. Risk of loss resides with the buyer. Should a data error
occur, the buyer may contact Apple to obtain another e-mail message.

Controlling Law
The validity, construction, and performance of these terms and conditions
shall be governed by and construed in accordance with the laws of the State
of California.

Taxes
Unless otherwise expressly indicated herein, all prices are exclusive of
federal, state, and local excise, sales, use or similar taxes. State and
local taxes, when applicable to this sale will appear as a separate line
item on the invoice and are governed by the tax laws of the State
of California.

Privacy
Apple requests from buyer only information which is necessary to complete
the credit card transaction.

Export Control
The buyer agrees to comply with all provisions of the U.S. Export
Administration Regulations governing the export and reexport of products
covered under this agreement.

Refund
QuickTime Pro offers a 30-day money-back guarantee. To receive a
refund for your upgrade to QuickTime Pro, you must remove your
personalized key from the software. For further information, see the
QuickTime web site at http://www.apple.com/quicktime/upgrade/refund/.

2

Cliff had a really good point.
I should make the change at a level where it is backwards compatible so
it doesn’t break any APIs.

This probably means two sets of functions, one with the appropriate
status parameter, and one with the existing parameters for backwards
compatibility and simplicity.

I want to get rid of the macro ugliness in the header files as well,
so this probably means two real sets of functions, one with a status
parameter, one without. Now I can get rid of the SDL_DEFUN() junk
in the header files.

It also means getting rid of the multiple libraries per platform and
building them the way normal libraries should be built. It will involve
quite a bit of work, as I isolate internal APIs and separate them out
into function interfaces, …

I will sleep on this.

Forwarded message: -------------------Date: Wed, 28 Jul 1999 03:01:47 -0600 (MDT)
From: ctm@ardi.com (Clifford T. Matthews)
Subject: Re: [SDL] Huge API change

“Sam” == Sam Lantinga writes:

Sam> Pro: Thread-safe error handling Internationalized error
Sam> messages Function-specific errors (i.e. no global errno
Sam> value) Better defined error conditions

I think you really need to separate the issues.

Sam> Con: Adds complexity to the API

Adds optional complexity. You know that I’m a big fan of backward
compatibility. You should be able to make it so that the mod is
bakward compatible at the source level. (Something you didn’t do when
you changed the the ReadLE32 routines … grr…).

[discussion snipped]

Add “Err” to discriminate between the versions of the routines that take
an error pointer and the ones that don’t. Allow your existing users to
use the ones that don’t.

You’ll then have

   SDL_BlitSurface

and SDL_BlitSurfaceErr

No code of consequence will break.

Sam> I still need to update the docs.  Once this issue is
Sam> resolved, I update the docs, and release the next stable
Sam> version of SDL, hopefully 1.0. :)

Personally I hope the next release is 0.10. I would like some time to
look at a lot of what you’ve done to see if there are other gotchas on
the way.

[discussion snipped]

–Cliff
ctm at ardi.com

------------------- end forwarded message.

3

Well, I think backwards compatibility should be maintained, either
by having error versions of every function or by some other way. My
suggestion is to divide the errors in some groups and let the user
register pointers to structures that will receive error information, one
pointer per error group. Something like SDL_InitError. If this function
isn’t called, the default behavior is set the pointers to NULL, and so
existing code won’t break and whoever wants to code without error checking
could do it. And we wouldn’t have duplicates for each and every function.
Just an alternative, anyway; as long as 1.0 is backwards compatible with
old code and lets the user decide if he wants error checking, I like it :)On Wed, 28 Jul 1999, Sam Lantinga wrote:

Cliff had a really good point.
I should make the change at a level where it is backwards compatible so
it doesn’t break any APIs.

This probably means two sets of functions, one with the appropriate
status parameter, and one with the existing parameters for backwards
compatibility and simplicity.

I want to get rid of the macro ugliness in the header files as well,
so this probably means two real sets of functions, one with a status
parameter, one without. Now I can get rid of the SDL_DEFUN() junk
in the header files.

It also means getting rid of the multiple libraries per platform and
building them the way normal libraries should be built. It will involve
quite a bit of work, as I isolate internal APIs and separate them out
into function interfaces, …

I will sleep on this.

Three Rings for the Elven Kings under this sky,
Seven for the Dwarf-Lords in their halls of stone,
Nine for the mortal men doomed to die,
One for the Dark Lord in his dark throne.

In the land of Mordor where shadows lie,
One Ring to rule them all, One Ring to find them
One Ring to bring them all and in darkness bind them
In the land of Mordor where shadows lie.

[]s, Andrei de A. Formiga
a.k.a. Ktulu ou Cthulhu
andrei at elogica.com.br
@Andrei_de_Araujo_For

4

Well, I think backwards compatibility should be maintained, either
by having error versions of every function or by some other way.

Backwards compatibility should not be a concern in development code. Once
SDL reaches 1.0, then the API will be fixed. Until then, it’s better to
make the change for the better. (Let’s face it, a search/replace is not a
hard thing to do.)

-ChuckOn Wed, 28 Jul 1999, Andrei de Araujo Formiga wrote:

5

I would have to say that an API change is probably the best thing you could do.
Why leave something broken if you know how to fix it. Let’s face it I have
tried out many other libraries for doing graphics in linux. SDL happens to be
the easiest one I have used yet and the fact that it includes thread safe
functions is a HUGE improvement over some other projects I have seen.

Of course I am a very new user and would hardly be impacted at all by the
change in the API.

DaveOn Wed, 28 Jul 1999, you wrote:

On Wed, 28 Jul 1999, Andrei de Araujo Formiga wrote:

Well, I think backwards compatibility should be maintained, either

by having error versions of every function or by some other way.

Backwards compatibility should not be a concern in development code. Once
SDL reaches 1.0, then the API will be fixed. Until then, it’s better to
make the change for the better. (Let’s face it, a search/replace is not a
hard thing to do.)

-Chuck