Re : Opaque Objects: summary

I’ve learned a technic to hide the implementation completly to the user.
(which is not, I know, what you meant really, but I wanted to talk about it briefly).

In a private header you have your structure declaration, as usual:

typdef struct {



Then an alias for pointers to that structure:

typedef struct Object * Object_ptr;

In the public header, you declare a public version of this structure, having the size
of the private structure:

typedef struct {



Then an alias to have a pointer to the public structure without the need to malloc:

typedef struct Object_pubObject_t[1];

Where “SIZEOF_Object” is to be replaced by the size of the private “Object” structure
in bytes.

Then, the whole public API only refers to “Object_t” and never to “Object”.
Each implementation function have to cast from the public type to the private type.

The memory policy is pretty simple:


/* Init the fields to a default value, allocate memory inside
the structure, etc. */

(… use “an_object”)

/* Clear allocated memory inside the structure */

You can find that kind of technic in the GMP library (

This technic works perfectly, I’ve tested it in a very serious mathematical library I’m developing in a research lab.

Doing this, the “Object” structure is fully opaque and you do not even reveal the
contents of the structure. (which is quite excessive, I know, but it can be useful in some cases).

Hope it was clear enough…


----- Message d’origine ----De : Edward Cullen
? : A list for developers using the SDL library. (includes SDL-announce)
Envoy? le : Lundi, 21 Juillet 2008, 21h16mn 13s
Objet : Re: [SDL] Opaque Objects: summary

julien CLEMENT wrote:

  • In a team, not all developers have the same level of competence,
    so to avoid problems, a stronger API would be necessary so that
    you don’t spend too much time finding hard-to-debug errors (like
    memory errors)

Change ‘In a team’ to ‘In general’.

Change ‘a stronger API’ to ‘a more intuitive and robust API’.

  • SDL is aimed at simplicity. It is coded in C, and adding extra checks
    or rewriting most functions would lead to “heaviness” which most
    SDL developer just don’t want.

I believe the interpretation of simplicity here is incorrect.

My understanding is that the majority SDL users want a simple-to-use
API that gives them access to OS services in a consistent way on many
platforms. I doubt whether performance is actually their main concern -
I personally have never profiled SDL itself, have you? I believe that
most people will simply take it on trust that SDL performs reasonably
well, based on the names behind it and some of the products it’s been
used in, such as UT2k4…

Implementing opaque objects to many of the larger structures would NOT
add much, if any overhead, as the majority of the structs and functions
concerned already pass-by-reference; it would be a ‘cosmetic’ change
aimed at reducing the cognitive load placed on the developer. (By
cognitive load, I mean the amount “I need to care about HOW this
works”). Note the word ‘reduce’ is does not mean ‘eliminate’; you can
never get away from the fact that this is a C API, something that I
have always been aware of (in spite of being accused of the opposite
many times).

  • If your team uses C/C++, then you ought to write your own wrapper
    aimed at less skilled programmers. Maybe it can be a good manner
    for them to get into SDL’s philosophy, and use it without the wrapper
    in the future.

But surely, if SDL’s API ‘is just right’ then I wouldn’t do that, I
would spend the effort on training, as the return would be greater?

  • If you can use a higher level language, the problem is almost solved.

Of course you can, but that’s not the point of the discussion, it is
about the C API and how it is best to express it.

  • You cannot impose a whole revolution in the SDL API, the answers you got
    (maybe not as professional as they should have been, I apologize for that)
    cleary show the reluctance to go in such a direction, although your
    motivation is completly well-founded.
    The reason is that you can bring more security on top of a low-level API
    so that both “hard coders” and “light coders” can find their interest, but
    the contrary would prevent “hard coders” from beeing satisfied.

Hmm… no one is trying to impose anything. I asked a question about a
particular technique commonly used in C APIs and whether it would
’improve’ SDLs APIs to make more use of it.

Your talk of revolution is misguided. Much of the discussion was centred
around the SDL_Surface structure. I deliberately chose this as an
example as is already semi-opaque. That is, the documentation for
SDL_Surface states that there are addition, undocumented, fields
(meaning that in order to find out the exact details, you have to refer
to the code). Therefore, moving SDL_Surface from semi-opaque to
fully-opaque would not be a revolution, merely an evolution.

To my mind, the discussion exposed 2 key facts:

  1. NOT knowing the exact layout of a structure can, in some situations,
    make debugging more difficult.

  2. That there are AT LEAST 2 techniques (preprocessor macros,
    ‘debugging’ option that makes object transparent) that can be used to
    mitigate this.

Also, both Xlib and the Win32 APIs make extensive use of opaque objects.
Given that one of SDLs primary goals is to abstract these APIs, then
there is a solid argument for continuing the use of opaque objects if
. That is to say, if it weren’t for SDL, you’d be dealing
with opaque objects anyway. Also, one can’t help but acknowledge the
fact that 2 separate APIs BOTH use similar techniques to solve the
same problem, there must be some validity in the technique, or at
least enough to make its use worth exploring.

(And before you say, “yeah, but M$ just copied Xlib’s API in order to
save effort or to encourage UNIX developers to switch to Windows.”, the
point remains valid; if M$ could have come up with a 'better’
technique, then surely they would have used it? If the X developers
could have come up with something better, surely they would have used it
when they went from X10 to X11?)

Hope I don’t miss a major point of the discussion and that you, Eddy, can
find a suitable technical solution to your problem.

My goal was to try it out, to experiment. Because of time constraints,
I wanted to try to cut-down the number of iterations I would have to go
through, by asking about the use of the technique before I start
trying to apply it. The only ‘problem’ I have is that people seem to
discourage any attempt to make a change, no matter how well informed or
proven that change might be!


SDL mailing list
SDL at


Envoyez avec Yahoo! Mail. Une boite mail plus intelligente