[Caml-list] SDL2 bindings, testers and feedback welcome

[Caml-list] SDL2 bindings, testers and feedback welcome

[Daniel Bünzli]

Hello, 

I have written thin bindings to SDL 2 using ocaml-ctypes. The binding
is finished but should be considered unstable: it was not thoroughly
tested and may still change as it has not been *used* yet. The purpose
of this unstable release is to:

1) Iron out the install procedure and test on a variety of platforms.
2) Get feedback about the design of the binding (see below). 

More precisely, apart from the eventual bugs, I'm interested in
getting feedback in the following areas:

* I used an 'a result = [ `Error | `Ok of 'a ] rather than an exception 
for functions that return error codes/null is error. I tend to lean
on exceptionless designs but I'm still unsure whether it is a good
idea that case. One of the problems is that SDL doesn't make a clear
distinction (at the signature level *and* in the documentation)
between programming errors (invalid_arg), exceptional errors
(e.g. out of memory) and non-exceptional errors (e.g. could not
access/setup a resource).

* The signature/approach of certain binding functions may be disputable 
or may need change to achieve reasonable performance. 

* Testing the binding to the joystick/game controller/force feedback api, 
I have none of these things in my hands.

I welcome discussions/ideas about these points and the general design
of the binding on github's issue tracker (http://github.com/dbuenzli/tsdl)

Note that the philosophy of the binding is to be "thin", that is a
mostly type-safe(r), minimal, hopefully efficient, one-to-one
binding. This means that I'm not interested in prettyfing the C API
like OCamlSDL does. I expect tsdl code to look like C SDL code
(including the inconsistent naming schemes) and the binding to be used
by programmers to build higher-level, more OCaml friendly, abstractions.

To install (only tested on osx and linux so far) you'll need at least SDL 2.0.1
installed on your system. Then:

opam repo add erratique-u http://erratique.ch/software/opam/unreleased
opam update && opam install tsdl 

On osx 10.8.5 with OCaml 4.01.0 there's a heisenbug I couldn't track so far
(see [1] for more info). Use 4.00.1 instead for now but note that the binding 
takes a long time to compile (~8 min on my machine) with that. 

If you want to hack the sources:

  git clone http://github.com/dbuenzli/tsdl 
  cd tsdl && ./build test.native && ./test.native

The documentation of the binding is here:

  http://erratique.ch/software/tsdl/doc/Tsdl

Best,

Daniel

[1] http://lists.ocaml.org/pipermail/ctypes/2013-December/000027.html

P.S. If anyone wonders, the existing OCamlSDL is a very good binding
to SDL 1.X, but SDL 2.0 is an entirely new, incompatible, API. Besides
SDL 2.0 changed to a zlib license, tsdl is under BSD3, OCamlSDL is
LGPL.

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Anthony Tavener]

[-- Attachment #1: Type: text/plain, Size: 3716 bytes --]

Sounds great! This is an item in my TODO list, also as "thin" bindings via
ctypes. I agree with leaving the nice abstraction to a higher level layer --
that generally happens anyway in a nontrivial project.

I have a controller and joystick, but no force. And some apps to port to
SDL2
to test with. Most of my use is the event system. Aside from that I just set
up a window for OpenGL.

Setting things up and installing once I send this email... :)



On Mon, Dec 16, 2013 at 11:11 PM, Daniel Bünzli <daniel.buenzli@erratique.ch
> wrote:

> Hello,
>
> I have written thin bindings to SDL 2 using ocaml-ctypes. The binding
> is finished but should be considered unstable: it was not thoroughly
> tested and may still change as it has not been *used* yet. The purpose
> of this unstable release is to:
>
> 1) Iron out the install procedure and test on a variety of platforms.
> 2) Get feedback about the design of the binding (see below).
>
> More precisely, apart from the eventual bugs, I'm interested in
> getting feedback in the following areas:
>
> * I used an 'a result = [ `Error | `Ok of 'a ] rather than an exception
> for functions that return error codes/null is error. I tend to lean
> on exceptionless designs but I'm still unsure whether it is a good
> idea that case. One of the problems is that SDL doesn't make a clear
> distinction (at the signature level *and* in the documentation)
> between programming errors (invalid_arg), exceptional errors
> (e.g. out of memory) and non-exceptional errors (e.g. could not
> access/setup a resource).
>
> * The signature/approach of certain binding functions may be disputable
> or may need change to achieve reasonable performance.
>
> * Testing the binding to the joystick/game controller/force feedback api,
> I have none of these things in my hands.
>
> I welcome discussions/ideas about these points and the general design
> of the binding on github's issue tracker (http://github.com/dbuenzli/tsdl)
>
> Note that the philosophy of the binding is to be "thin", that is a
> mostly type-safe(r), minimal, hopefully efficient, one-to-one
> binding. This means that I'm not interested in prettyfing the C API
> like OCamlSDL does. I expect tsdl code to look like C SDL code
> (including the inconsistent naming schemes) and the binding to be used
> by programmers to build higher-level, more OCaml friendly, abstractions.
>
> To install (only tested on osx and linux so far) you'll need at least SDL
> 2.0.1
> installed on your system. Then:
>
> opam repo add erratique-u http://erratique.ch/software/opam/unreleased
> opam update && opam install tsdl
>
> On osx 10.8.5 with OCaml 4.01.0 there's a heisenbug I couldn't track so far
> (see [1] for more info). Use 4.00.1 instead for now but note that the
> binding
> takes a long time to compile (~8 min on my machine) with that.
>
> If you want to hack the sources:
>
>   git clone http://github.com/dbuenzli/tsdl
>   cd tsdl && ./build test.native && ./test.native
>
> The documentation of the binding is here:
>
>   http://erratique.ch/software/tsdl/doc/Tsdl
>
> Best,
>
> Daniel
>
> [1] http://lists.ocaml.org/pipermail/ctypes/2013-December/000027.html
>
> P.S. If anyone wonders, the existing OCamlSDL is a very good binding
> to SDL 1.X, but SDL 2.0 is an entirely new, incompatible, API. Besides
> SDL 2.0 changed to a zlib license, tsdl is under BSD3, OCamlSDL is
> LGPL.
>
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
>

[-- Attachment #2: Type: text/html, Size: 5010 bytes --]

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Florent Monnier]

2013/12/17, Daniel Bünzli wrote:
> Hello,
Hi Daniel!

Thanks for your previous help for compilations on Raspberry Pi, since
then I enjoy so much programming on this small machine, and I've been
able to make mini-demos for kids with it, which was such a happy
moment for me (and I hope for them too).

> I have written thin bindings to SDL 2 using ocaml-ctypes. The binding

I don't know anything about "ocaml-ctypes", I will have to add on my
TODO list to search for sme blog posts and/or tutorials about it.

> is finished but should be considered unstable: it was not thoroughly
> tested and may still change as it has not been *used* yet. The purpose
> of this unstable release is to:
>
> 1) Iron out the install procedure and test on a variety of platforms.

I can test it on Mageia Linux and on MS/Windows with Cygwin Terminal
with MingW's compilator.

Should we test SDL 2.0.0 or 2.0.1 (or both?)

Can I request you later to test a compilation on OSX?

> 2) Get feedback about the design of the binding (see below).

The most interesting it there :)

> More precisely, apart from the eventual bugs, I'm interested in
> getting feedback in the following areas:
>
> * I used an 'a result = [ `Error | `Ok of 'a ] rather than an exception
> for functions that return error codes/null is error. I tend to lean
> on exceptionless designs but I'm still unsure whether it is a good
> idea that case.

I also prefer exceptionless designs, but in practice I found that it's
more painfull for writting quick and dirty small/mini demos and quick
experimentations.
And experimentation is important for writting screensavers,
mini-games, and various multi-media/infographic things.

But I would say (IMHO) that it would be good to have both, an
exceptionfull module for beginning, and an exceptionless module for
the rewritting of the initial drafts.

Being myself a perfectionist, I found interesting to migrate what I
felt is perfection, from very well written code, into very quickly
written code, I mean as in a race or a challenge :-)

>                 One of the problems is that SDL doesn't make a clear
> distinction (at the signature level *and* in the documentation)

SDL 1/2 are C libs.
We should not expect something tailored for our language.

If something is missing there, this our job to provide it, and then to share it.

More precisely I found very interesting several initiatives available
around, like for example the idea behind the XML description of the
API of the XCB C library.

http://xcb.freedesktop.org/dist/xcb-proto-1.9.tar.gz

I think this could be an interesting project to make an equivalent for SDL 2.
And from there trying to make something that would tend to be a
standard for any kind of C libs.
These API descriptions could then be used for different purposes by
different projects.

I would like to elaborate and discuss more on the topic, and to share
my experimentations but I have now to go to the state ajency for
unemployed people. If someone is interested to sponsor my
experimentations, I could allocate more energy on it than when I'm
doing it as a volunteer. to be continued...

> between programming errors (invalid_arg), exceptional errors
> (e.g. out of memory) and non-exceptional errors (e.g. could not
> access/setup a resource).

Ya we should fork SDL into an SDLERR project that would return proper
error codes for every possible type of errors. Maybe there would be
some sponsors for such a project.

> * The signature/approach of certain binding functions may be disputable
> or may need change to achieve reasonable performance.

could you elaborate?

> * Testing the binding to the joystick/game controller/force feedback api,
> I have none of these things in my hands.

I bought a 5 euro joypad last year for testing SFML2 and SDL2.
I can test the joypad events.

> I welcome discussions/ideas about these points and the general design
> of the binding on github's issue tracker (http://github.com/dbuenzli/tsdl)

Thanks for accepting feedbacks.

> Note that the philosophy of the binding is to be "thin", that is a
> mostly type-safe(r), minimal, hopefully efficient, one-to-one
> binding. This means that I'm not interested in prettyfing the C API
> like OCamlSDL does.

I share your views and tastes.
(Even if I like both ways.)

But thin could be understood in different ways, and addapted to the
idioms of the language.
for example a piece of ocaml--sdl code like:

   let stuff = Sdlmodule.func params in

will then be rewritten in C by copy-pasting the func-stub :

   SDL_t stuff = SDL_ModFunc(params);
   if (stuff != 0) {
      myprint("Err: %s", SDL_GetError());
      myexit() // or myNextLoop();
   }

On the OCaml formulation my equivalent will be a try on the main entry
display function, with the exceptional case to be either nothing or a
failsafe handling, that has its own close equivalent in pure C.

>                     I expect tsdl code to look like C SDL code
> (including the inconsistent naming schemes) and the binding to be used
> by programmers to build higher-level, more OCaml friendly, abstractions.
>
> To install (only tested on osx and linux so far) you'll need at least SDL
> 2.0.1
> installed on your system. Then:
>
> opam repo add erratique-u http://erratique.ch/software/opam/unreleased
> opam update && opam install tsdl
>
> On osx 10.8.5 with OCaml 4.01.0 there's a heisenbug I couldn't track so far
> (see [1] for more info). Use 4.00.1 instead for now but note that the
> binding
> takes a long time to compile (~8 min on my machine) with that.
>
> If you want to hack the sources:
>
>   git clone http://github.com/dbuenzli/tsdl
>   cd tsdl && ./build test.native && ./test.native
>
> The documentation of the binding is here:
>
>   http://erratique.ch/software/tsdl/doc/Tsdl
>
> Best,
>
> Daniel
>
> [1] http://lists.ocaml.org/pipermail/ctypes/2013-December/000027.html
>
> P.S. If anyone wonders, the existing OCamlSDL is a very good binding
> to SDL 1.X, but SDL 2.0 is an entirely new, incompatible, API.

The API is not entirely new. A lot is compatible, and a compatibility
layer has been carefully designed to help progressive and painless
migrations.

Without the Licensing issues on OCamlSDL, we could have migrated it to SDL 2.X

I would still want to try it if only the authors could be reached to
ask them permission to switch from the highly restrictive and
incompatible current license of OCamlSDL into the more convenient
zlib/png license of SDL 2.

>                                                                Besides
> SDL 2.0 changed to a zlib license, tsdl is under BSD3, OCamlSDL is
> LGPL.

Indeed, and LGPL without exception on static linking needed by ocamlers.

Would it be indiscreet to ask you if you wrote this code as a
volunteer or if you got paid for it, and how much? If that's
indiscreet, please just ignore this question.

-- 
Cheers
Florent

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Daniel Bünzli]

Le mardi, 17 décembre 2013 à 15:17, Florent Monnier a écrit :
> I can test it on Mageia Linux and on MS/Windows with Cygwin Terminal
> with MingW's compilator.
>  
> Should we test SDL 2.0.0 or 2.0.1 (or both?)
As long as tsdl is not released I plan to follow the latest 2.0.X, since SDL bugs get fixed in the process.

> But I would say (IMHO) that it would be good to have both, an
> exceptionfull module for beginning, and an exceptionless module for
> the rewritting of the initial drafts.

I'm not fond of diluting APIs into various incarnations, it augments the overall bureaucracy and I like to have a single way of doing things. Getting rid of handling these `Error cases seems an `ignore` or monad away so I tend to lean on keeping it the way it is now.

> > * The signature/approach of certain binding functions may be disputable
> > or may need change to achieve reasonable performance.
>  
> could you elaborate?

If you take a function like Sdl.render_draw_lines [1] a lot of copying is involved for transforming that point list into a pointer on an array of points. Hence I also provide the function Sld.render_draw_lines_ba [2] which takes the point list as a bigarray and allows to perform the call without any copying, depending on where your data comes from this can be much more efficient. Since I didn't use the binding yet, I may have missed less obvious opportunities.  

[1] http://erratique.ch/software/tsdl/doc/Tsdl.Sdl.html#VALrender_draw_lines
[2] http://erratique.ch/software/tsdl/doc/Tsdl.Sdl.html#VALrender_draw_lines_ba



> Would it be indiscreet to ask you if you wrote this code as a
> volunteer or if you got paid for it, and how much?  

1/3 (~1 week) of the code was sneaked during my stay at OCaml Labs when I was bored working on vg. The remaining 2/3 are self-funded but I need part of it for a paid project.  

Best,

Daniel

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Erkki Seppala]

Florent Monnier <monnier.florent@gmail.com> writes:

> More precisely I found very interesting several initiatives available
> around, like for example the idea behind the XML description of the
> API of the XCB C library.
>
> http://xcb.freedesktop.org/dist/xcb-proto-1.9.tar.gz

I suppose it doesn't detract your point, but xcb-proto actually
describes the line protocol of X, not the X library interface or XCB
library interface though the latter can be inferred from it based on the
fact it's generated. So the new XCB-based libraries for interacting with
the X server then are generated from those (but Xlib is not related to
this). They are not very useful for binding per se.

But they could be used for generating XCB-based OCaml library
interacting directly with X. (I have actually written a tool based on
those that decodes live X traffic, but it was in Python (for code
generation) and C (for doing the work).)

> Ya we should fork SDL into an SDLERR project that would return proper
> error codes for every possible type of errors. Maybe there would be
> some sponsors for such a project.

Well, I think that it may be a bit unrealistic to expect this kind of
fork to get very popular. I think in most common SDL use cases people
just don't care much about errors :(. (Ie. games: either work or they
don't.)

But a documentation effort or a tool for extracting thrown error strings
and then building towards more consistent error management, that I think
would easily be upstreamable.

-- 
  _____________________________________________________________________
     / __// /__ ____  __               http://www.modeemi.fi/~flux/\   \
    / /_ / // // /\ \/ /                                            \  /
   /_/  /_/ \___/ /_/\_\@modeemi.fi                                  \/

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Anthony Tavener]

[-- Attachment #1: Type: text/plain, Size: 1842 bytes --]

On Tue, Dec 17, 2013 at 11:54 PM, Erkki Seppala <flux@modeemi.cs.tut.fi>wrote:

>
> Well, I think that it may be a bit unrealistic to expect this kind of
> fork to get very popular. I think in most common SDL use cases people
> just don't care much about errors :(. (Ie. games: either work or they
> don't.)
>

I care about errors, but in practice the only functions I use which have
errors
of concern are during initialization. Once system resources are acquired,
I'm
mostly reading events and swapping buffers.

I'm translating a smaller project (mostly works, but for some reason my
controller
is not detected, so far -- works with sdlcaml/SDL1.2). Admittedly, dealing
with
`Error | `Ok was a bit annoying. A lot of functions I really don't care
much (getting
device names), so an abstraction which assigns on `Ok, or defaults on
`Error is
fine.

Something I'm not so keen on is that event types and event values aren't
constants I can pattern match on, so I have a lot of "| t when t = "...

  method process_event ev =
    match Sdl.Event.(get ev typ) with
    | t when t = Sdl.Event.key_down ->
      begin match Sdl.Event.(get ev keyboard_scancode) with
        | t when t = Sdl.Scancode.s -> thrustp <- {thrustp with z = 1.};
true
        | t when t = Sdl.Scancode.w -> thrustn <- {thrustn with z = 1.};
true

These are matchable constants in sdlcaml. With Tsdl, the constants are
brought in
as let-bindings... looks like Daniel has something nifty to make this a lot
easier
but I haven't looked into it yet.


Summary of parts tested and working for me:
 -window with opengl context
 -event handling: mouse and keyboard
 -grabbing and hiding cursor, also release and show

Next is figuring out why my game controller isn't detected, and maybe
plugging in
a joystick and another kind of controller too. First, time for some sleep.
:)

[-- Attachment #2: Type: text/html, Size: 2859 bytes --]

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Daniel Bünzli]

Le mercredi, 18 décembre 2013 à 09:05, Anthony Tavener a écrit :
> Something I'm not so keen on is that event types and event values aren't
> constants I can pattern match on, so I have a lot of "| t when t = "...
>  
> method process_event ev =
> match Sdl.Event.(get ev typ) with  
> | t when t = Sdl.Event.key_down ->
> begin match Sdl.Event.(get ev keyboard_scancode) with
> | t when t = Sdl.Scancode.s -> thrustp <- {thrustp with z = 1.}; true
> | t when t = Sdl.Scancode.w -> thrustn <- {thrustn with z = 1.}; true
>  
> These are matchable constants in sdlcaml.  
Actually that's something in the TODO:

https://github.com/dbuenzli/tsdl/blob/master/TODO.md

I don't think it's useful to convert let's say Sdl.Init enumerants to variants as those are mainly used for setting up state and less likely to be pattern matched upon. But at least functions from Sdl.{scancode,keycode} to an polymorphic variant will be added. Feel free to make your desire more precise in the issue tracker.  

> With Tsdl, the constants are brought in  
> as let-bindings... looks like Daniel has something nifty to make this a lot easier
> but I haven't looked into it yet.

Not so nifty, you still have to enumerate them. A C program outputs them, that's here:

https://github.com/dbuenzli/tsdl/blob/master/support/consts_stub.c
  
> Next is figuring out why my game controller isn't detected, and maybe plugging in
> a joystick and another kind of controller too. First, time for some sleep. :)

Just want to mention that if you are not sure whether the problem lies in the binding or in SDL itself there's a minimal C example with compilation instructions that you can use to try to reproduce the problem in: cd `opam config var tsdl:doc`

Best,

Daniel  

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Florent Monnier]

2013/12/18, Erkki Seppala wrote:
> Florent Monnier wrote not only:
>
>> More precisely I found very interesting several initiatives available
>> around, like for example the idea behind the XML description of the
>> API of the XCB C library.
>>
>> http://xcb.freedesktop.org/dist/xcb-proto-1.9.tar.gz
>
> I suppose it doesn't detract your point, but xcb-proto actually
> describes the line protocol of X, not the X library interface or XCB
> library interface though the latter can be inferred from it based on the
> fact it's generated. So the new XCB-based libraries for interacting with
> the X server then are generated from those (but Xlib is not related to
> this). They are not very useful for binding per se.
>
> But they could be used for generating XCB-based OCaml library
> interacting directly with X. (I have actually written a tool based on
> those that decodes live X traffic, but it was in Python (for code
> generation) and C (for doing the work).)

What I meant is that annotate the C headers, or similar approaches are
limited if it's about to make a generic way that could be used in most
(or maybe almost all) cases.

A proper description of the APIs would make it possible to divert to
different languages (and maybe even other kind of applications).

XcbProto is designed for our best friend Python, but its upstream
immediatly proposed to complete it with additional elements that we
would need for our programming language of choice.

> Well, I think that it may be a bit unrealistic to expect this kind of
> fork to get very popular. I think in most common SDL use cases people
> just don't care much about errors :(. (Ie. games: either work or they
> don't.)

Sorry it was just ironic :)
Sam already does quite a lot enough. We should not ask too much, or if
we do we should just do ourself what we request from someone else.

> But a documentation effort or a tool for extracting thrown error strings
> and then building towards more consistent error management, that I think
> would easily be upstreamable.

Then please try!

-- 
Best regards
Florent

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Kakadu]

Fellas,

I have added [1] function TTF_openFont but when I use it I receive
`Error and don't know why. Do you know how to debug it? Maybe I did
something wrong in OCaml definitions?

Kakadu

[1] https://github.com/Kakadu/tsdl/commit/44115cbdee92911eae9b1d51ce33da86392da965#diff-844c2aaff3869f0a29cc34c69b019276R824



On Wed, Dec 18, 2013 at 12:18 PM, Florent Monnier
<monnier.florent@gmail.com> wrote:
> 2013/12/18, Erkki Seppala wrote:
>> Florent Monnier wrote not only:
>>
>>> More precisely I found very interesting several initiatives available
>>> around, like for example the idea behind the XML description of the
>>> API of the XCB C library.
>>>
>>> http://xcb.freedesktop.org/dist/xcb-proto-1.9.tar.gz
>>
>> I suppose it doesn't detract your point, but xcb-proto actually
>> describes the line protocol of X, not the X library interface or XCB
>> library interface though the latter can be inferred from it based on the
>> fact it's generated. So the new XCB-based libraries for interacting with
>> the X server then are generated from those (but Xlib is not related to
>> this). They are not very useful for binding per se.
>>
>> But they could be used for generating XCB-based OCaml library
>> interacting directly with X. (I have actually written a tool based on
>> those that decodes live X traffic, but it was in Python (for code
>> generation) and C (for doing the work).)
>
> What I meant is that annotate the C headers, or similar approaches are
> limited if it's about to make a generic way that could be used in most
> (or maybe almost all) cases.
>
> A proper description of the APIs would make it possible to divert to
> different languages (and maybe even other kind of applications).
>
> XcbProto is designed for our best friend Python, but its upstream
> immediatly proposed to complete it with additional elements that we
> would need for our programming language of choice.
>
>> Well, I think that it may be a bit unrealistic to expect this kind of
>> fork to get very popular. I think in most common SDL use cases people
>> just don't care much about errors :(. (Ie. games: either work or they
>> don't.)
>
> Sorry it was just ironic :)
> Sam already does quite a lot enough. We should not ask too much, or if
> we do we should just do ourself what we request from someone else.
>
>> But a documentation effort or a tool for extracting thrown error strings
>> and then building towards more consistent error management, that I think
>> would easily be upstreamable.
>
> Then please try!
>
> --
> Best regards
> Florent
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Vu Ngoc San]

Hi Kakadu

I think you just forgot TTF_Init.

I have added a couple of functions (see below), and it works very well.

Best wishes
San

module TTF = struct
   type _font
   type font_struct = _font structure
   let font_struct : font_struct typ = structure "TTF_Font"
   type font = font_struct ptr
   let font_opt : font option typ = ptr_opt font_struct
   let font : font typ = ptr font_struct
   let init =
     foreign "TTF_Init"
       (void @-> returning zero_to_ok)
   let was_init =
     foreign "TTF_WasInit"
       (void @-> returning bool)
   let open_font =
     foreign "TTF_OpenFont"
       (string @-> int @-> returning (some_to_ok font_opt) )
   let close_font =
     foreign "TTF_CloseFont"
       (font @-> returning void)
   let render_text_blended =
     foreign "TTF_RenderText_Blended"
       (font @-> string @-> color @-> returning (some_to_ok surface_opt))
   let render_utf8_blended =
     foreign "TTF_RenderUTF8_Blended"
       (font @-> string @-> color @-> returning (some_to_ok surface_opt))
   let render_unicode_blended =
     foreign "TTF_RenderUNICODE_Blended"
       (font @-> string @-> color @-> returning (some_to_ok surface_opt))
   let size_utf8 =
     foreign "TTF_SizeUTF8"
       (font @-> string @-> ptr int @-> ptr int @-> returning zero_to_ok)
   let size_utf8 f s =
     let w = allocate int 0 in
     let h = allocate int 0 in
     match size_utf8 f s w h with
       | `Ok () -> `Ok (!@ w, !@ h) | `Error -> `Error
end


Le 22/12/2013 11:01, Kakadu a écrit :
> Fellas,
>
> I have added [1] function TTF_openFont but when I use it I receive
> `Error and don't know why. Do you know how to debug it? Maybe I did
> something wrong in OCaml definitions?
>
> Kakadu
>
> [1] https://github.com/Kakadu/tsdl/commit/44115cbdee92911eae9b1d51ce33da86392da965#diff-844c2aaff3869f0a29cc34c69b019276R824
>
>
>
> On Wed, Dec 18, 2013 at 12:18 PM, Florent Monnier
> <monnier.florent@gmail.com> wrote:
>> 2013/12/18, Erkki Seppala wrote:
>>> Florent Monnier wrote not only:
>>>
>>>> More precisely I found very interesting several initiatives available
>>>> around, like for example the idea behind the XML description of the
>>>> API of the XCB C library.
>>>>
>>>> http://xcb.freedesktop.org/dist/xcb-proto-1.9.tar.gz
>>> I suppose it doesn't detract your point, but xcb-proto actually
>>> describes the line protocol of X, not the X library interface or XCB
>>> library interface though the latter can be inferred from it based on the
>>> fact it's generated. So the new XCB-based libraries for interacting with
>>> the X server then are generated from those (but Xlib is not related to
>>> this). They are not very useful for binding per se.
>>>
>>> But they could be used for generating XCB-based OCaml library
>>> interacting directly with X. (I have actually written a tool based on
>>> those that decodes live X traffic, but it was in Python (for code
>>> generation) and C (for doing the work).)
>> What I meant is that annotate the C headers, or similar approaches are
>> limited if it's about to make a generic way that could be used in most
>> (or maybe almost all) cases.
>>
>> A proper description of the APIs would make it possible to divert to
>> different languages (and maybe even other kind of applications).
>>
>> XcbProto is designed for our best friend Python, but its upstream
>> immediatly proposed to complete it with additional elements that we
>> would need for our programming language of choice.
>>
>>> Well, I think that it may be a bit unrealistic to expect this kind of
>>> fork to get very popular. I think in most common SDL use cases people
>>> just don't care much about errors :(. (Ie. games: either work or they
>>> don't.)
>> Sorry it was just ironic :)
>> Sam already does quite a lot enough. We should not ask too much, or if
>> we do we should just do ourself what we request from someone else.
>>
>>> But a documentation effort or a tool for extracting thrown error strings
>>> and then building towards more consistent error management, that I think
>>> would easily be upstreamable.
>> Then please try!
>>
>> --
>> Best regards
>> Florent
>>
>> --
>> Caml-list mailing list.  Subscription management and archives:
>> https://sympa.inria.fr/sympa/arc/caml-list
>> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
>> Bug reports: http://caml.inria.fr/bin/caml-bugs

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Ashish Agarwal]

[-- Attachment #1: Type: text/plain, Size: 2876 bytes --]

On Tue, Dec 17, 2013 at 1:11 AM, Daniel Bünzli
<daniel.buenzli@erratique.ch>wrote:

* I used an 'a result = [ `Error | `Ok of 'a ] rather than an exception
>

1. The `Error case doesn't give any information about what the error is, so
this is equivalent to 'a option. I recommend 'a option as a return type
only when there can be only a single error. For example, I think it's okay
for Map.find to return None since it clearly means the item was not found.

2. If you have `Error carry a value, you have Core's ('ok, 'err) Result.t
(ignoring for the moment that you have polymorphic variants, which is
good). Then the question becomes what will 'err be in each specific case.
The important criteria is that the types you choose must unify, or else it
will be very difficult to compose functions into bigger programs. One
option is to always make 'err = string. This is lightweight, let's you
provide informative messages, and simplifies your type to contain a single
type variable. This is similar to Core's Or_error, but instead of string,
they define Error.t which has some other benefits.

3. If you want to enable robust error handling, you get tempted to define
'err as a more specialized type. Adding the criteria that each instance of
'err must unify, you end up using polymorphic variants, e.g. `Error of [>
`not_found | `timed_out ]. We used this approach in some production code,
but I'm starting to feel it is not worth the hassle. It is very hard to
maintain.

4. So we're back to option 2, which doesn't allow robust error handling
because the error type isn't rich enough. Thus, the question is why is it
any better than raising exceptions. It is not making your code any safer
because you're forced to program monadically, where you systematically
ignore every error, just like if all your functions were raising
exceptions. In the end, the only difference between option 2 and
exception-ful style is that your type signature documents the possibility
of an error. It only says that "some" error occurs. You still have to
define what this error is about in your text documentation. In exchange for
this, you've complicated all of your type signatures and forced monadic
programming everywhere. In the end, raising exceptions seems fine to me.
You can define multiple exceptions to increase the chance that specific
errors can be handled when needed.

Disclaimer: my opinion about this changes every day.


Other comments:

* What is the T in Tsdl? I don't see any T on the SDL website.
* Your type `barray` would be better named `big_array`. In this case,
`bigarray` would also be okay since it would be consistent with the module
Bigarray to which this type refers.

I don't like random single letters in names, which is also a problem in
your Vg and Gg project names. Thanks for all your great libraries!

[-- Attachment #2: Type: text/html, Size: 3486 bytes --]

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Daniel Bünzli]

Le mardi, 17 décembre 2013 à 18:05, Ashish Agarwal a écrit :
> On Tue, Dec 17, 2013 at 1:11 AM, Daniel Bünzli <daniel.buenzli@erratique.ch (mailto:daniel.buenzli@erratique.ch)> wrote:
>  
> > * I used an 'a result = [ `Error | `Ok of 'a ] rather than an exception
>  
> 1. The `Error case doesn't give any information about what the error is, so this is equivalent to 'a option. I recommend 'a option as a return type only when there can be only a single error. For example, I think it's okay for Map.find to return None since it clearly means the item was not found.
>  
> 2. If you have `Error carry a value, you have Core's ('ok, 'err) Result.t (ignoring for the moment that you have polymorphic variants, which is good). Then the question becomes what will 'err be in each specific case. The important criteria is that the types you choose must unify, or else it will be very difficult to compose functions into bigger programs. One option is to always make 'err = string. This is lightweight, let's you provide informative messages, and simplifies your type to contain a single type variable. This is similar to Core's Or_error, but instead of string, they define Error.t which has some other benefits.
>  
> 3. If you want to enable robust error handling, you get tempted to define 'err as a more specialized type. Adding the criteria that each instance of 'err must unify, you end up using polymorphic variants, e.g. `Error of [> `not_found | `timed_out ]. We used this approach in some production code, but I'm starting to feel it is not worth the hassle. It is very hard to maintain.
>  
> 4. So we're back to option 2, which doesn't allow robust error handling because the error type isn't rich enough. Thus, the question is why is it any better than raising exceptions. It is not making your code any safer because you're forced to program monadically, where you systematically ignore every error, just like if all your functions were raising exceptions. In the end, the only difference between option 2 and exception-ful style is that your type signature documents the possibility of an error. It only says that "some" error occurs. You still have to define what this error is about in your text documentation. In exchange for this, you've complicated all of your type signatures and forced monadic programming everywhere. In the end, raising exceptions seems fine to me. You can define multiple exceptions to increase the chance that specific errors can be handled when needed.
>  
> Disclaimer: my opinion about this changes every day.

A lot more can be said about that and it's highly independent from the setting. However I think this discussion is mostly irrelevant here since we are constrained by the loose design of the underlying library which, as I said, doesn't differentiate/document enough its errors and provides them only as strings. So what I did is to return `Error whenever the function may return an error and the documentation indicates that Sdl.get_error () can be used to get more information (they don't expose error codes). What I could have done though is to have that error message in the `Error case. As for using options instead of this result type I really want to be able to distinguish at the type level between the following two functions (see the corresponding C documentation):

http://erratique.ch/software/tsdl/doc/Tsdl.Sdl.html#VALget_hint
http://erratique.ch/software/tsdl/doc/Tsdl.Sdl.html#VALrw_from_file

  
> * What is the T in Tsdl? I don't see any T on the SDL website.

Thin (bindings to) SDL. I could have used Sdl but I don't like to take ownership of toplevel names that are used in other settings.
  
>  
> * Your type `barray` would be better named `big_array`. In this case, `bigarray` would also be okay since it would be consistent with the module Bigarray to which this type refers.

Why not. Maybe I should prefer b_array which is used by Gg.
  
> I don't like random single letters in names, which is also a problem in your Vg and Gg project names.

It's not random ! It's short cryptic acronyms. Vector graphics, geometry and graphics…
  
> Thanks for all your great libraries!

You are welcome,  

Daniel   

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Ashish Agarwal]

[-- Attachment #1: Type: text/plain, Size: 1886 bytes --]

On Tue, Dec 17, 2013 at 12:47 PM, Daniel Bünzli <daniel.buenzli@erratique.ch
> wrote:

As for using options instead of this result type I really want to be able
> to distinguish at the type level between the following two functions (see
> the corresponding C documentation):
>

The desire to distinguish between a successful non-result vs an error is
reasonable, but it's hard to know where to draw the line. Is it an error
for Map.find to not find the item you asked for? Maybe. Maybe not. I would
just say consider that introducing a new type has a cost. Your users have
to learn one more thing and, in this case, get embroiled in yet another
monad.


> * What is the T in Tsdl? I don't see any T on the SDL website.
>
> Thin (bindings to) SDL.


Ugh.


I could have used Sdl but I don't like to take ownership of toplevel names
> that are used in other settings.
>

Admirable, but if you're defining a library that binds to a C library, I
think it is reasonable to take that name. We rarely have multiple OCaml
libraries that bind to the same C library. In this case, the library name
could be sdl or ocaml-sdl (or sdl2 or ocaml-sdl2). I usually don't like
adding "ocaml-" to library names because it is silly; of course it is an
ocaml library. However, when binding to a C library, it makes some sense to
distinguish between the OCaml and original C libraries.


Why not. Maybe I should prefer b_array which is used by Gg.
>

I'd have the same criticism. It is the single letter I don't like.


>
> > I don't like random single letters in names, which is also a problem in
> your Vg and Gg project names.
>
> It's not random ! It's short cryptic acronyms. Vector graphics, geometry
> and graphics…
>

I misspoke. What I meant is: I don't like short cryptic acronyms. They
appear random to me because I don't know what they mean.

[-- Attachment #2: Type: text/html, Size: 3307 bytes --]

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Anthony Tavener]

[-- Attachment #1: Type: text/plain, Size: 2392 bytes --]

On Tue, Dec 17, 2013 at 11:57 AM, Ashish Agarwal <agarwal1975@gmail.com>wrote:

> On Tue, Dec 17, 2013 at 12:47 PM, Daniel Bünzli <
> daniel.buenzli@erratique.ch> wrote:
>
>> I could have used Sdl but I don't like to take ownership of toplevel
>> names that are used in other settings.
>>
>
> Admirable, but if you're defining a library that binds to a C library, I
> think it is reasonable to take that name. We rarely have multiple OCaml
> libraries that bind to the same C library. In this case, the library name
> could be sdl or ocaml-sdl (or sdl2 or ocaml-sdl2). I usually don't like
> adding "ocaml-" to library names because it is silly; of course it is an
> ocaml library. However, when binding to a C library, it makes some sense to
> distinguish between the OCaml and original C libraries.
>
>
There are multiple sdl and opengl bindings. I think there was another
ocamlsdl aside from the current OCamlSDL, and there's sdlcaml which is
packed with glcaml. For OpenGL, there's LablGL, glMLite, and glcaml. And
these are the package names, rather than the module names. It's ripe
territory for naming clashes. :) I've taken an initial stab at my own SDL2
bindings and I've been using Sdl2 as the module name (sdlcaml uses Sdl as
it's module name), but expected that I might change that to something more
distinct if I were to share it.

This does raise a question though... should we be concerned about
module-name clashes for libraries which should be used "one or the other"?
I don't know if some build tool might find libraries by module name now or
in future -- if so, unique module names are important. If not, then I guess
using the same module name is fine, but with a distinct package name.


>> > I don't like random single letters in names, which is also a problem in
>> your Vg and Gg project names.
>>
>> It's not random ! It's short cryptic acronyms. Vector graphics, geometry
>> and graphics…
>>
>
> I misspoke. What I meant is: I don't like short cryptic acronyms. They
> appear random to me because I don't know what they mean.
>
>
Sdl, Glut, Qt, Gtk, Xml... it's only cryptic at first, and what would you
really use which is less cryptic? I can understand the desire to have a
library name which at least gives a hint of it's utility, but this isn't
possible in the general case without getting some cumbersome names!

[-- Attachment #2: Type: text/html, Size: 3826 bytes --]

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Ashish Agarwal]

[-- Attachment #1: Type: text/plain, Size: 748 bytes --]

On Tue, Dec 17, 2013 at 2:45 PM, Anthony Tavener
<anthony.tavener@gmail.com>wrote:

This does raise a question though... should we be concerned about
> module-name clashes for libraries which should be used "one or the other"?
>

You never know if someone wants to link in both libraries, so I would say
yes, you should be concerned.


Sdl, Glut, Qt, Gtk, Xml... it's only cryptic at first, and what would you
> really use which is less cryptic? I can understand the desire to have a
> library name which at least gives a hint of it's utility, but this isn't
> possible in the general case without getting some cumbersome names!
>

Good point. So, I guess I'm saying try hard for a short intuitive name
first, but yes, sometimes it's not possible.

[-- Attachment #2: Type: text/html, Size: 1557 bytes --]

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Yotam Barnoy]

[-- Attachment #1: Type: text/plain, Size: 954 bytes --]

What's wrong with thin_sdl? Sounds much nicer than tsdl to me. Or slim_sdl.

-Yotam Barnoy


On Wed, Dec 18, 2013 at 10:40 AM, Ashish Agarwal <agarwal1975@gmail.com>wrote:

> On Tue, Dec 17, 2013 at 2:45 PM, Anthony Tavener <
> anthony.tavener@gmail.com> wrote:
>
> This does raise a question though... should we be concerned about
>> module-name clashes for libraries which should be used "one or the other"?
>>
>
> You never know if someone wants to link in both libraries, so I would say
> yes, you should be concerned.
>
>
> Sdl, Glut, Qt, Gtk, Xml... it's only cryptic at first, and what would you
>> really use which is less cryptic? I can understand the desire to have a
>> library name which at least gives a hint of it's utility, but this isn't
>> possible in the general case without getting some cumbersome names!
>>
>
> Good point. So, I guess I'm saying try hard for a short intuitive name
> first, but yes, sometimes it's not possible.
>
>

[-- Attachment #2: Type: text/html, Size: 2135 bytes --]

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Daniel Bünzli]

Le mercredi, 18 décembre 2013 à 19:02, Yotam Barnoy a écrit :
> What's wrong with thin_sdl? Sounds much nicer than tsdl to me. Or slim_sdl.

Right, I have an idea: let's vote on this !

For the record I'm interested in getting feedback about the design of the binding from a usability point of view (especially the result type vs exception issue), not in pointless discussions about the name of the library. The case has been made for having short toplevel names. The name won't change, deal with it or move on making your own with the fucking good toplevel name of your choice.

Daniel

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Ashish Agarwal]

[-- Attachment #1: Type: text/plain, Size: 1005 bytes --]

On Wed, Dec 18, 2013 at 2:53 PM, Daniel Bünzli
<daniel.buenzli@erratique.ch>wrote:

> Le mercredi, 18 décembre 2013 à 19:02, Yotam Barnoy a écrit :
> > What's wrong with thin_sdl? Sounds much nicer than tsdl to me. Or
> slim_sdl.
>
> Right, I have an idea: let's vote on this !
>
> For the record I'm interested in getting feedback about the design of the
> binding from a usability point of view (especially the result type vs
> exception issue), not in pointless discussions about the name of the
> library. The case has been made for having short toplevel names. The name
> won't change, deal with it or move on making your own with the fucking good
> toplevel name of your choice.
>

You ask for feedback. People are kind enough to spend time giving you some,
but you get angry that the advice is not exactly what you are looking for.
This is a public mailing list, and there is no obligation to discuss only
precisely what you want. You are free to ignore advice you don't like.

[-- Attachment #2: Type: text/html, Size: 1381 bytes --]

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Daniel Bünzli]

Le mercredi, 18 décembre 2013 à 23:29, Ashish Agarwal a écrit :
> You ask for feedback. People are kind enough to spend time giving you some, but you get angry that the advice is not exactly what you are looking for. This is a public mailing list, and there is no obligation to discuss only precisely what you want. You are free to ignore advice you don't like.

I am not angry, I make precise what I'm looking for in order not to waste the time of everybody on this public mailing list.

Daniel
  

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Daniel Bünzli]

Le mardi, 17 décembre 2013 à 19:57, Ashish Agarwal a écrit :
> The desire to distinguish between a successful non-result vs an error is reasonable, but it's hard to know where to draw the line.

In that case the line is pretty clear, any function that may return an error about the call through Sdl.get_error gets that type. But regarding the overall discussion, for me it boils down to one of these choices:

1) Convert all error conditions to exceptions and say in the docs any function in the Sdl module may raise Sdl.Error  
2) Keep it as it is now.
  
> Is it an error for Map.find to not find the item you asked for? Maybe. Maybe not.  

Actually this case is quite easy IMHO. When you devise a map data structure you should have both Map.get : 'a t -> key -> 'a, that raises *Invalid_argument* if the key is unbound (that's for code paths were you know the value is in there) and Map.find : 'a t -> key -> 'a option, that returns None if the key is unbound (that's for code paths were you don't know if the value is there).  

> I misspoke. What I meant is: I don't like short cryptic acronyms. They appear random to me because I don't know what they mean.  
Ok then ! The thing is that when you use combinators approaches and/or get type errors you don't want to have long winded name prefixes. I think the name just after the prefix is more important and here I don't use short cryptic acronyms: Vg.image, Vg.glyph, Vg.path, Vg.renderer etc.  

Best,

Daniel

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Francois Berenger]

On 12/18/2013 05:26 AM, Daniel Bünzli wrote:
> Le mardi, 17 décembre 2013 à 19:57, Ashish Agarwal a écrit :
>> The desire to distinguish between a successful non-result vs an error is reasonable, but it's hard to know where to draw the line.
>
> In that case the line is pretty clear, any function that may return an error about the call through Sdl.get_error gets that type. But regarding the overall discussion, for me it boils down to one of these choices:
>
> 1) Convert all error conditions to exceptions and say in the docs any function in the Sdl module may raise Sdl.Error
> 2) Keep it as it is now.
>
>> Is it an error for Map.find to not find the item you asked for? Maybe. Maybe not.
>
> Actually this case is quite easy IMHO. When you devise a map data structure you should have both Map.get : 'a t -> key -> 'a, that raises *Invalid_argument* if the key is unbound (that's for code paths were you know the value is in there) and Map.find : 'a t -> key -> 'a option, that returns None if the key is unbound (that's for code paths were you don't know if the value is there).
>
>> I misspoke. What I meant is: I don't like short cryptic acronyms. They appear random to me because I don't know what they mean.
> Ok then ! The thing is that when you use combinators approaches and/or get type errors you don't want to have long winded name prefixes. I think the name just after the prefix is more important and here I don't use short cryptic acronyms: Vg.image, Vg.glyph, Vg.path, Vg.renderer etc.

Here is what I learned some time ago on this very same mailing-list;
at the top of some .ml file:

module Vg = Vector_graphics

I _love_ it.

-- 
Best regards,
Francois Berenger.

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Erkki Seppala]

Francois Berenger <berenger@riken.jp> writes:

> Here is what I learned some time ago on this very same mailing-list;
> at the top of some .ml file:
>
> module Vg = Vector_graphics

Indeed. And to do it project-wide one can just put those into common.ml
and open Common at top of the project files. This way one gets to use
the same aliases in every file.

Actually, once I've even done:

module Fo = FooBarBaz20
module FooBarBaz20 = struct end

in the file make it more difficult to accidentally use the full name and
making things look inconsistent :).

-- 
  _____________________________________________________________________
     / __// /__ ____  __               http://www.modeemi.fi/~flux/\   \
    / /_ / // // /\ \/ /                                            \  /
   /_/  /_/ \___/ /_/\_\@modeemi.fi                                  \/

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Daniel Bünzli]

Le mercredi, 18 décembre 2013 à 02:13, Francois Berenger a écrit :
> Here is what I learned some time ago on this very same mailing-list;
> at the top of some .ml file:
>  
> module Vg = Vector_graphics
>  
> I _love_ it.
If you'll do that anyway, why have a long name in the first place ? Everyone defining his own pet names makes code less readable.  

Daniel

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Florent Monnier]

2013/12/18, Daniel Bünzli wrote:
> Le mercredi, 18 décembre 2013 à 02:13, Francois Berenger a écrit :
>> Here is what I learned some time ago on this very same mailing-list;
>> at the top of some .ml file:
>>
>> module Vg = Vector_graphics
>>
>> I _love_ it.
> If you'll do that anyway, why have a long name in the first place ? Everyone
> defining his own pet names makes code less readable.

Hi Daniel,

I also like these kind of solutions like:
module Md = MyModule
let () = let foo = Md.f1 a in Md.f2 b

because I found that in practice if I use a long module name like
"MyModule" everywhere in my code the code becomes heivy. With a
diminutive (.nickname?) the code is lighter and easier to read. But
easier to read only if i know what this diminutive (/nickname?) refers
to. I found easier to find back what this diminutive refers to if it's
available at the beginning of the code file.

I'm not trying to say that this is the perfect ideal solution for
everyone, I just want to share that this is a solution that works well
for me.
And maybe someone else would find that this solution works well too
for him or her.

-- 
Florent

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Florent Monnier]

2013/12/17, Ashish Agarwal wrote:
> On Tue, Dec 17, 2013 at 12:47 PM, Daniel Bünzli wrote:
[...]
>> I could have used Sdl but I don't like to take ownership of toplevel names
>> that are used in other settings.
>>
>
> Admirable, but if you're defining a library that binds to a C library, I
> think it is reasonable to take that name. We rarely have multiple OCaml
> libraries that bind to the same C library. In this case, the library name
> could be sdl or ocaml-sdl (or sdl2 or ocaml-sdl2). I usually don't like
> adding "ocaml-" to library names because it is silly; of course it is an
> ocaml library. However, when binding to a C library, it makes some sense to
> distinguish between the OCaml and original C libraries.

There is also another project that took the base radical name SDL2
concatenated with OCaml. The upstream of this draft just took this
name because of a lack of imagination, and also because at the
beginning he was willing to write something that would be painless to
migrate from the origine OCamlSDL. This upstream really don't mind to
rename it into something else if someone suggests a nice name.

Maybe "rsdl2" standing for "relays to SDL2" :o)

> I misspoke. What I meant is: I don't like short cryptic acronyms. They
> appear random to me because I don't know what they mean.

This is an interesting point. Since several months, I made the test to
use a localised translation which is not an acronym for talking about
"OSM" to some people in the street and in local shops, and it really
makes it easier to talk about this project then. But such a trick is
maybe not needed for a project targetting people who like cryptic
computer stuff :o)

-- 
Florent

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Erkki Seppala]

Daniel Bünzli <daniel.buenzli@erratique.ch> writes:

> However I think this discussion is mostly irrelevant here
> since we are constrained by the loose design of the underlying library
> which, as I said, doesn't differentiate/document enough its errors and
> provides them only as strings. So what I did is to return `Error
> whenever the function may return an error and the documentation
> indicates that Sdl.get_error () can be used to get more information
> (they don't expose error codes).

Amazing! I checked SDL2 out and indeed, the only way to do reporting is
with SDL_SetError(const char *fmt, ...);. I imagine it must be a great
easy way to make simple error reporting, but it sure doesn't make it
easy to handle them.

Here is an overly-complicated and slightly unrealistic solution:

- Find each error from the code automatically

Examples:
  SDL_SetError("SDL not built with video support");
  SDL_SetError("Couldn't open %s", filename);

- Transform them into:
type error = [ `SDL_not_build_with_video_support
             | `Couldnt_open of string ]

- And maybe:
exception SDL_Error of error

With some code analysis one could even discover what errors are thrown
by which functions :-o. (Actually without that the previous mapping
without exceptions wouldn't be very useful.)

This scheme of course fails with

  SDL_SetError("%s%s%s", prefix ? prefix : "", prefix ? ": " : "",
  message);

which would need manual handling.

So perhaps it's not realistic, not worth the trouble and not aligned
with your goals of making a very thin wrapping layer. Maybe this kind of
'safer' layer could be built as an additional layer over Tsdl.

But I think a small enhancement would be making the error an `Error of
string. It would make the stringly typed error handling of SDL more
apparent to the user and give more direct suggestion on how to deal with
them.

> Thin (bindings to) SDL. I could have used Sdl but I don't like to take ownership of toplevel names that are used in other settings.

I think the name might make one think the bindings are for
libsdl1. Would Tsdl2 be too verbose?

Thanks for great work! I'm sure to check the bindings out in practice
the next time I find myself needing to deal with the task SDL is
suitable for :).

-- 
  _____________________________________________________________________
     / __// /__ ____  __               http://www.modeemi.fi/~flux/\   \
    / /_ / // // /\ \/ /                                            \  /
   /_/  /_/ \___/ /_/\_\@modeemi.fi                                  \/

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Florent Monnier]

2013/12/17, Daniel Bünzli wrote:
> Hello,
Hi again,

> I have written thin bindings to SDL 2 using ocaml-ctypes. The binding
> is finished but should be considered unstable: it was not thoroughly
> tested and may still change as it has not been *used* yet. The purpose
> of this unstable release is to:
>
> 1) Iron out the install procedure and test on a variety of platforms.

and your "README.md" file contains:

> Installation
[...]
> If you don't use `opam` consult the [`opam`](opam) file for
> build instructions and a complete specification of the dependencies.

$ ./pkg/pkg-git
$ ./pkg/build true
ocamlfind ocamlopt unix.cmxa -I /usr/lib/ocaml/ocamlbuild
/usr/lib/ocaml/ocamlbuild/ocamlbuildlib.cmxa -linkpkg myocamlbuild.ml
/usr/lib/ocaml/ocamlbuild/ocamlbuild.cmx -o myocamlbuild
ocamlfind ocamldep -package ctypes -modules src/tsdl.mli > src/tsdl.mli.depends
+ ocamlfind ocamldep -package ctypes -modules src/tsdl.mli >
src/tsdl.mli.depends
ocamlfind: Package `ctypes' not found
Command exited with code 2.

In your README file there is a section contains a section
"Installation" and the dependencies are listed there but in the first
paragraph that should be the introduciton of what is the project.
I would suggest to migrate the dependencies listing into either the
"Installation" paragraph or  into a new section called "Dependencies".

Another small detail is that for people getting components through
packages, the "Installation" paragraph is usually not usefull. At the
Mageia project of software distribution, it is recommanded that when
the compilation/installation are provided in a separated file than the
README file, to not provide it. So if the compilation / installation
informations was in an "INSTALL.txt" file then the Mageia users would
escape from how such a piece of software component is compiled,
installed (and optionally packaged, but this is another story).

Another very small detail is that in the "README.md" file it is written:

> ## Installation
[...]
> If you don't use `opam` consult the [`opam`](opam) file for
> build instructions and a complete specification of the dependencies.

so I opened the "opam" file and found these build instructions:

> build:
> [
>   ["./pkg/pkg-git" ]
>   ["./pkg/build" "true" ]
> ]

i then half blindly trusted these commands:

./pkg/pkg-git
./pkg/build true

which did "compiled" the lib but not "installed" it (the poor joke
that i'm attempting to make is that the paragraph is called
"Installation", and that following it doesn't lead me to a point where
I get something installed.)

So if some early beginners are reading this email, installation can be
achieved in this following way:

after the compilation step done by:
./pkg/pkg-git
./pkg/build true

Then go in the build directory:
_build/src/

Log into admin user, for those using the ocamlfind installer:
ocamlfind install tsdl ../pkg/META *.a *.cm[iatx] *.cmx[as] *.cmti *.mli *.so

For people not using ocamlfind:
OCAMLDIR=`ocamlc -where`
DESTDIR="$OCAMLDIR/tsdl"
mkdir $DESTDIR
cp *.a *.cm[iatx] *.cmx[as] *.cmti *.mli *.so $DESTDIR/

Then I'm able to run the samples in the test directory:

ocaml unix.cma bigarray.cma -I +ctypes ctypes.cma
ctypes-foreign-base.cma ctypes-foreign-unthreaded.cma -I +tsdl
tsdl.cma tsdl.cma min.ml

min.ml produces the expected result (on mageia linux) (by expected I
mean the same than minc.c)

ocamlc -c -I +tsdl fmts.ml
ocaml unix.cma bigarray.cma -I +ctypes ctypes.cma
ctypes-foreign-base.cma ctypes-foreign-unthreaded.cma -I +tsdl
tsdl.cma tsdl.cma fmts.cmo sdlevents.ml

while running sdlevents.ml I can see logs in the console about key
strokes events and mouse events, but nothing for the joypad.

When I'm launching an equivalent example through another project that
also relays sdl2 function calls from ocaml:

https://github.com/blue-prawn/OCamlSDL2/blob/master/examples/ex_event.ml

https://github.com/blue-prawn/OCamlSDL2/blob/1c9608cd4b473e8b7e60ada1fa1402c0504e56c2/examples/ex_event.ml

I can see the joypad events correctly.

-- 
Florent

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Florent Monnier]

2013/12/19, Florent Monnier wrote:
> 2013/12/17, Daniel Bünzli wrote:
>> * Testing the binding to the joystick/game controller/force feedback api,
>> I have none of these things in my hands.
[...]
> while running sdlevents.ml I can see logs in the console about key
> strokes events and mouse events, but nothing for the joypad.
[...]

with the following patch the logs then display events from the joypad:

================================================================
--- dbuenzli/tsdl-1904fb/test/sdlevents.ml
+++ dbuenzli/tsdl-JO/test/sdlevents.ml
@@ -20,6 +20,22 @@
       match Sdl.create_window ~w:640 ~h:480 "SDL events" flags with
       | `Error -> log_err " Create window:"
       | `Ok w ->
+
+            begin match Sdl.num_joysticks () with
+            | `Error -> log_err " Num Joysticks:"
+            | `Ok nj ->
+                log " Num Joysticks: %d" nj;
+                for i = 0 to nj-1 do
+                  match Sdl.joystick_open i with
+                  | `Error -> log_err " Opening Joysticks %d:" i
+                  | `Ok j ->
+                      match Sdl.joystick_name j with
+                      | `Error -> log_err " Getting name for joystick %d:" i
+                      | `Ok jname ->
+                          log " Joystick `%s` opened" jname
+                done;
+            end;
+
             Sdl.start_text_input ();
             let e = Sdl.Event.create () in
             try
================================================================

i'll issue it on gh

-- 
Florent

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Daniel Bünzli]

Le jeudi, 19 décembre 2013 à 06:20, Florent Monnier a écrit :

> i then half blindly trusted these commands:
>  
> ./pkg/pkg-git
> ./pkg/build true
>  
> which did "compiled" the lib but not "installed" it (the poor joke
> that i'm attempting to make is that the paragraph is called
> "Installation", and that following it doesn't lead me to a point where
> I get something installed.)


Well if you want to be picky the paragraph tells you how to *install* with opam and says to look at the `opam` file for *build* instructions...  

That being said after that you are almost there, just use opam-installer [1] on the toplevel `tsdl.install` file that these build commands generated. Especially since you are packaging for a distribution, this tool can generate you a shell script for installation (and eventually you'll be able to apply this to all of my packages).  

(N.B. manual installation is for advanced users who know what they are doing so I'm not going to maintain instructions about that)

Best,

Daniel

[1] https://sympa.inria.fr/sympa/arc/caml-list/2013-12/msg00068.html

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Florent Monnier]

2013/12/19, Daniel Bünzli wrote:
>
> Le jeudi, 19 décembre 2013 à 06:20, Florent Monnier a écrit :
>
>> which did "compiled" the lib but not "installed" it (the poor joke
>> that i'm attempting to make is that the paragraph is called
>> "Installation", and that following it doesn't lead me to a point where
>> I get something installed.)
>
> Well if you want to be picky the paragraph tells you how to *install* with
> opam and says to look at the `opam` file for *build* instructions...

Oh yes! One day I'll have to learn reading the English language :-)

> That being said after that you are almost there, just use opam-installer [1]
> on the toplevel `tsdl.install` file that these build commands generated.
> Especially since you are packaging for a distribution, this tool can
> generate you a shell script for installation (and eventually you'll be able
> to apply this to all of my packages).

Using the Opam method will not help on platforms where I'm unable to
compile Opam.
(For example on MS/Windows)

> (N.B. manual installation is for advanced users who know what they are doing
> so I'm not going to maintain instructions about that)

Compiling Opam the "file-by-file" way on MS/Windows is also not a piece of cake.

> Best,
>
> Daniel
>
> [1] https://sympa.inria.fr/sympa/arc/caml-list/2013-12/msg00068.html
>
-- 
Regards,
Florent

Re: [Caml-list] SDL2 bindings, testers and feedback welcome

[Daniel Bünzli]

Le mardi, 17 décembre 2013 à 07:11, Daniel Bünzli a écrit :
> * I used an 'a result = [ `Error | `Ok of 'a ] rather than an exception
> for functions that return error codes/null is error. I tend to lean
> on exceptionless designs but I'm still unsure whether it is a good
> idea that case. One of the problems is that SDL doesn't make a clear
> distinction (at the signature level *and* in the documentation)
> between programming errors (invalid_arg), exceptional errors
> (e.g. out of memory) and non-exceptional errors (e.g. could not
> access/setup a resource).

I found that in practice directly returning the string you get by SDL_GetError () in the `Error case is much more convenient. E.g. with the above type your bind looks like this:

let ( >>= ) x f = match x with  
| `Error -> `Error_msg (Sdl.get_error ())  
| `Error_msg _ as e -> e
| `Ok v -> f v



which is needlessly unconvenient. So I'm changing that type to  

'a result = [ `Error of string | `Ok of 'a ]

and you always directly get the result of Sdl.get_error () in the `Error case.  

Best,

Daniel