Guile-SDL 0.5.0 available

[Thien-Thi Nguyen]

release notes:

  A slew of changes, many of them backward incompatible; code that works
  w/ previous versions of Guile-SDL will MOST LIKELY BE BROKEN by this
  one.  On the other hand, we've added the "alpha" weasel word to README
  (see excerpt below) and tried to not be complete jerks by marking some
  items for "planned retirement".

  Hee hee, how's THAT for "unstable"?

  For the adventurous who build from a repo checkout, please note that
  bootstrap no longer requires SNUGGLE, as its functionality was merged
  into Guile-BAUX.

  thi

README excerpt:

  Guile-SDL is a set of modules that provide bindings for various
  Simple DirectMedia Layer (http://www.libsdl.org) libraries.
  
  Most of the SDL functions are wrapped, with the exception of a
  few functions that are too C-centric.  The SDL threads, audio
  and network functions are not included.  However, there are
  (optionally configured) bindings for SDL_mixer and SDL_ttf.
  
  Also included is SDL_gfx 2.0.22 (by Andreas Schiffler) source
  code (LGPL 2.1) and bindings for it.
  
  This is alpha code (pre 1.0 release), tested with various,
  but not all, versions of Guile and SDL.  It may have bugs,
  and the interfaces may change from version to version.
  
NEWS excerpt:

  - 0.5.0 | 2013-07-19

        WARNING: There are several entries marked "[BI]",
        which stands for "backward incompatible".

    - planned retirement

      - 2013-12-31 -- procs that return an alist

        These procs return an alist, which burdens the caller w/ the
        destructuring / decode dance:

         (sdl sdl) cd-get-nth-track
         (sdl sdl) cd-frames->msf
         (sdl sdl) joystick-get-ball
         (sdl mixer) query-spec
         (sdl ttf) font:glyph-metrics
         (sdl ttf) font:size-text
         (sdl ttf) font:size-utf8
         (sdl sdl) get-video-info
         (sdl sdl) get-rgb
         (sdl sdl) get-rgba
         (sdl sdl) get-caption
         (sdl sdl) get-mouse-state
         (sdl sdl) get-mouse-relative-state

        See "new procs returning values" below for their replacements.

      - 2013-12-31 -- procs that query/set event processing model

        These procs query or set the processing model of the specified
        type or joystick, respectively:

         (sdl sdl) event-state
         (sdl sdl) joystick-event-state

        For uniformity, they have undergone interface changes in this
        release (see below) but even so, their interface suffers from
        under-understanding and over-engineering that is difficult to
        back out of.  So it goes; we (will) bail.

        See "new event model procs" below for their replacements.

      - 2013-12-31 -- ‘(sdl sdl) set-alpha!’

        The calling convention for this proc is fugly beyond belief.
        Its replacement is ‘surface-alpha!’ (see below).

      - 2013-12-31 -- ‘(sdl sdl) set-color-key!’

        Like ‘set-alpha!’, this proc exists and persists w/o beauty.
        Its replacement is ‘surface-color-key!’ (see below).

      - 2013-12-31 -- ‘(sdl sdl) peep-events’

        Yet another unshapen mess, grody to the max.  Die, die, die!
        See "new event queue procs" below for its replacement.

    - bugfixes

      - ‘non-member-symbol’ detected and error thrown

        All procs that take SYMBOL (enums or flags), or a list of SYMBOL
        (flags) now throw ‘non-member-symbol’ if SYMBOL is not a member
        of the respective enumstash or flagstash.  Previously, such
        symbols were silently ignored.  E.g., given:

         (define (ugh)
           (flags->number
            (flagstash:event-mask)
            '(SDL_MOUSEMOTIONMASK
              x
              SDL_KEYDOWNMASK)))

        Behavior was:

         (event:type (make-event 'foo))
         => #f

         (ugh)
         => 20

        Behavior now:

         (event:type (make-event 'foo))
         error-> ERROR: In procedure make-event:
         error-> ERROR: invalid event-type: foo

         (ugh)
         error-> ERROR: In procedure flags->number:
         error-> ERROR: invalid event-mask: x

        This change is marked not "[BI]" because although ‘enum->number’
        and ‘flags->number’ can no longer be used as-is for probing,
        that is an unlikely (bordering on nonsensical) usage.

      - ‘(sdl sdl) push-event’ returns boolean

        Previously this proc returned an integer, incorrectly documented
        as "1 for success, 0 for queue full, -1 for other errors" (the
        underlying SDL func returns 0 on success, -1 on error).  Now, it
        returns ‘#t’ on success, and ‘#f’ otherwise.

      - ‘(sdl sdl) set-mod-state’ does not insist on integer arg

        Regression introduced 2003-11-08 (Guile-SDL 0.2.0) during
        foof-to-ttn transition.  Briefly: 0/ arg type initially exact
        with type check; 1/ foof changed type to flags and commented
        out now-obsolete type check; 2/ ttn commented in the check;
        3/ test coverage lacking until this release.  Ugh, so it goes.

      - [BI] flags dropped: ‘KMOD_NONE’, ‘KMOD_RESERVED’

        These were part of ‘flagstash:event-mod’, though they should
        never have been.  Since ‘KMOD_RESERVED’ is never generated by
        SDL, its removal has little import.  OTOH, code that currently
        checks for "no key modifiers pressed" against ‘(KMOD_NONE)’ (a
        list of one symbol) needs to now check against the empty list.

      - ‘number->flags’ et al always return a list, never ‘#f’

        Previously, if the given integer was not covered by the flags,
        ‘number->flags’ would return ‘#f’, losing information.  Now,
        that non-zero "remainder" is consed onto the returned list, at
        the head.  For example, given the hypothetical flagstash ‘foo’:

         1 -- a
         2 -- b
         4 -- c

        then:
                                  was        now
         (number->flags  0 foo)   => #f      => ()
         (number->flags  5 foo)   => (a c)   => (a c)
         (number->flags 13 foo)   => #f      => (8 a c)

        The underlying mechanism of ‘number->flags’ is shared w/ these
        procs:

         (sdl sdl) was-init
         (sdl sdl) get-mod-state
         (sdl sdl) get-mouse-state               ; see below
         (sdl sdl) get-mouse-relative-state      ; see below
         (sdl ttf) font:style

        They, too, now always return a list, never ‘#f’.

      - negative integers for some event field-setter procs

        These event field-setter procs now accept negative integers:

         event:motion:set-xrel!
         event:motion:set-yrel!
         event:jaxis:set-value!
         event:jball:set-xrel!
         event:jball:set-yrel!
         event:resize:set-w!
         event:resize:set-h!

        Previously, they would signal error for integers less than zero.
        Note that the latter two are for excruciating fidelity w/ the
        SDL C struct; synthesizing a resize event w/ negative width or
        height is probably Not Universally Appreciated.  YMMV.  YHBW.

      - ‘cd-name’ and ‘joystick-name’ can return ‘#f’

        Previously, these (sdl sdl) procs would segfault if SDL returned
        a null cdrom or joystick name, respectively.  Now, they return
        ‘#f’ in that case.

      - fixes to ‘(sdl sdl) button?’

        - all buttons documented

        This was a long-standing documentation omission.

        - works as documented

        Since the beginning, this proc failed to actually consult the
        mouse button state, returning a non-sensical result.  Now it
        calls (the C equivalent of) ‘get-mouse-state’ internally.

      - ‘cd-null?’ and ‘joystick-null?’ dropped

        These procs serve no purpose.  The cdrom object and the joystick
        object are never "null"; if errors occur in their construction,
        the respective procs ‘cd-open’ and ‘joystick-open’ return ‘#f’.

        See also "procs signal error if cdrom/joystick not open" below.

      - ‘string->image’ dropped

        This was an experiment.  The bug fixed in its removal is the
        ignorance of just how unsuitable Scheme strings are for binary
        data.  Something like it might well return in the future.

      - ‘(sdl sdl) gl-enums’ dropped

        This was unused, and inappropriately named.  Something like it
        will return along w/ other features to support OpenGL, someday.

      - ‘(sdl sdl) make-keysym’ dropped

        This was useless, buggy (suffering from the same mishandling as
        ‘set-mod-state’, above), and gratuitous (no underlying SDL func).
        It was a bug to maintain it for this long.

    - procs require uvec arg(s), no longer accept normal vectors

        As pre-announced in Guile-SDL 0.4.0 (2011-12-15) NEWS, the
        following procs now require their arg(s) to be uniform vectors:

         (sdl gfx) draw-polygon             s16
         (sdl gfx) draw-aa-polygon          s16
         (sdl gfx) draw-textured-polygon    s16
         (sdl gfx) draw-bezier              s16
         (sdl sdl) create-cursor            u8
         (sdl sdl) set-gamma-ramp           u16

        A normal vector now results in a wrong-type-arg error.

    - horizontal / vertical flipping preserves surface depth

        Previously, ‘horizontal-flip-surface’, ‘vertical-flip-surface’
        and ‘vh-flip-surface’ always returned a new surface w/ depth 16.
        Now, the depth is the same as that of the source surface.

    - ‘(sdl sdl) event-state’ returns new state

        Previously, the return value was specified only on query.
        Now, it is specified for all cases.

    - ‘(sdl mixer) set-music-command’ now takes ‘#f’ also

        Normally, the string arg ‘command’ to ‘set-music-command’
        specifies the external command to use for subsequent music load
        and playback.  As a special case, you can now specify ‘#f’ as
        the command to revert (or ensure) internal playback routines
        use.

    - symbolic "mouse button"

        The mouse buttons are symbols in the set:

         left middle right
         wheel-up wheel-down
         x1 x2

        The latter two are "extended buttons" probably, for the fully
        fondle-able fist friend (groan).

      - new proc: ‘(sdl sdl) mouse-bxy’

        This obsoletes both ‘get-mouse-state’ and
        ‘get-mouse-relative-state’.

      - mouse state procs can return symbolic state

        Normally, the ‘state’ value in the alist returned by
        ‘get-mouse-state’ and ‘get-mouse-relative-state’ is an integer.
        These procs now take an optional arg which, if non-‘#f’, means
        to return instead a (possibly empty) list of mouse buttons.

      - [BI] motion state get/set

        Previously, ‘event:motion:state’ and ‘event:motion:set-state!’
        returned and accepted an integer value, respectively.  Now the
        value is symbolic (list for getter, single symbol or list for
        setter), from the set of mouse buttons.

      - [BI] button button get/set

        Previously, ‘event:button:button’ and ‘event:button:set-button!’
        returned and accepted an integer value, respectively.  Now the
        value is a symbol, from the set of mouse buttons.

    - [BI] ‘(sdl sdl) get-app-state’ rv symbolic

        This proc now returns a possibly empty list of symbols from the
        set: ‘mousefocus’, ‘inputfocus’, ‘active’.

    - [BI] active event gain/state fully symbolic

        The procs ‘event:active:gain’ and ‘event:active:set-gain!’ now
        return and accept, respectively, a symbol, one of: ‘gained’ or
        ‘lost’.

        The procs ‘event:active:gain’ and ‘event:active:set-gain!’ now
        return and accept, respectively, a list of symbols from the same
        set as ‘get-app-state’ (above).

    - [BI] key/mbutton/jbutton state fully symbolic

        These getter and setter procs:

         event:key:state      event:key:set-state!
         event:button:state   event:button:set-state!
         event:jbutton:state  event:jbutton:set-state!

        now return and accept, respectively, a symbolic state, one of:
        ‘released’ or ‘pressed’.  Likewise for ‘joystick-get-button’.

    - [BI] ‘(sdl sdl) joystick-event-state’ fully symbolic

        This proc now takes and returns a single symbol of the set:
        ‘SDL_QUERY’, ‘SDL_IGNORE’, ‘SDL_ENABLE’.

    - [BI] joystick hat position fully symbolic

        The procs ‘event:jhat:value’ and ‘event:jhat:set-value!’ now
        return and accept, respectively, a list of one or two symbols
        from the set: ‘centered’, ‘up’, ‘right’, ‘down’, ‘left’.  The
        four two-symbol cases are permutations of the vertical and
        horizontal symbols.

    - [BI] procs signal error if cdrom/joystick not open

        These ‘(sdl sdl)’ procs used to return -1 or ‘#f’ (i.e., a
        nonsense value) if given a cdrom or joystick object that has
        been ‘cd-close’d or ‘joystick-close’d, respectively:

         cd-status             joystick-index
         cd-in-drive?          joystick-num-axes
         cd-get-num-tracks     joystick-num-balls
         cd-get-cur-track      joystick-num-hats
         cd-get-cur-frame      joystick-num-buttons
         cd-get-nth-track      joystick-get-axis
         cd-play-tracks        joystick-get-ball
         cd-play               joystick-get-hat
         cd-pause              joystick-get-button
         cd-resume             joystick-close
         cd-stop
         cd-eject
         cd-close

        Now they signal "cdrom not open" or "joystick not open"
        error, respectively.

    - [BI] fading-status symbols for ‘(sdl mixer)’ procs changed

        Here is a table showing the previous and current set of possible
        return values (symbols) for ‘fading-music’ and ‘fading-channel’:

         was: MIX_NO_FADING         now: no
              MIX_FADING_OUT             out
              MIX_FADING_IN              in

    - ‘(sdl mixer) fading-status’ dropped

        This enumstash is no longer useful due to the previous change.
        (The one that holds the new set of symbols is internal.)

    - ‘(sdl gfx) font-rotation!’ accepts also integer

        You can specify an integer as well as symbolic ROTATION:

         0  means  none
         1         clockwise
         2         upside-down
         3         counter-clockwise

        The behavior w/ other integers is undefined.

    - colormap procs accept ‘start’ index

        Previously, ‘set-colors!’ and ‘set-palette’ always modified the
        colormap starting from index 0.  Now, you can completely specify
        the portion to modify with additional optional arg ‘start’.

    - new procs returning values

        Here are the multiple-values-returning replacement procs for
        those that return an alist (see "planned retirement" above):

         (sdl sdl) cd-nth-track-itlo
         (sdl sdl) frames-msf
         (sdl sdl) joystick-ball-xy
         (sdl mixer) device-ffc
         (sdl ttf) font:glyph-xXyYa
         (sdl ttf) text-wh
         (sdl ttf) utf8-wh
         (sdl sdl) video-cmf
         (sdl sdl) pixel-rgb
         (sdl sdl) pixel-rgba
         (sdl sdl) caption-ti
         (sdl sdl) mouse-bxy (for both get-mouse-state
                                  and get-mouse-relative-state)

        The names depart from the scheme used by their peers (which is
        less than beautiful, but so it goes...); the last component is a
        mnemonic for both the number of values and the values' names.
        For example: "-wh" implies two values: width and height.

        For the most part, when the alist returned by the old proc has N
        entries, the new proc returns N values.  The unique exception is
        ‘video-cmf’, which compresses the nine separate boolean-value
        entries into a single list of symbols.  See manual.

        Some old procs return ‘#f’ if there are problems, rather than an
        alist.  The new ones signal error, instead.

        Lastly, ‘mouse-bxy’ cosolidates two procs.  When all is done
        (after 2013-12-31), the net change is API shrinkage, yeah!

    - new event model procs

        The new ‘(sdl sdl)’ procs ‘event-type-handling’ and
        ‘joystick-polling’ query only, by default.  If optional arg
        SETTING is specified, its truth value is used to enable or
        disable event TYPE processing and joystick polling,
        respectively.

        These procs obsolete ‘event-state’ and ‘joystick-event-state’,
        respectively.

    - new proc: ‘(sdl sdl) surface-alpha!’

        This obsoletes ‘(sdl sdl) set-alpha!’.

    - new proc: ‘(sdl sdl) surface-color-key!’

        This obsoletes ‘(sdl sdl) set-color-key!’.

    - new keysyms

        The count of keysyms grew by 98 (was 133 now 231).  New:

         SDLK_WORLD_0 through SDLK_WORLD_95 (total 96)
         SDLK_COMPOSE
         SDLK_UNDO

    - new event queue procs

        The new ‘(sdl sdl)’ procs ‘evqueue-add’, ‘evqueue-peek’ and
        ‘evqueue-get’ provide rationalized interfaces to the underlying
        ‘SDL_PeepEvents’ (i.e., ‘peep-events’, thus obsoleted).  New
        feature: ‘evqueue-peek’ can return either a list of matching
        events or a count of them.

    - new proc: ‘(sdl sdl) kotk’

        This is the "keeper of the konstants", which provides a
        simplified (yet more complete) reflection, obsoleting
        ‘enumstash-enums’ and ‘flagstash-flags’.

    - [BI] conversion procs take stash name

        These procs now accept a stash name (symbol) as their first arg:

         enum->number
         number->enum
         flags->number
         number->flags

        You can use ‘(sdl sdl) kotr’ to get a list of stash names.

    - [BI] stash objects dropped

        These elements are now recognized as better maintained internal
        (as an implementation detail) than exposed to Scheme:

         enumstash: (sdl sdl) event-types
         enumstash: (sdl sdl) event-keys
         enumstash: (sdl sdl) event-states
         enumstash: (sdl sdl) alpha-enums
         enumstash: (sdl gfx) font-rotations

         proc: (sdl sdl) flagstash:init
         proc: (sdl sdl) flagstash:event-mod
         proc: (sdl sdl) flagstash:event-mask
         proc: (sdl sdl) flagstash:video
         proc: (sdl sdl) flagstash:palette
         proc: (sdl sdl) flagstash:overlay
         proc: (sdl ttf) flagstash:ttf

        Luckily, there is no loss of introspection; see "conversion
        procs take stash name" above.  Where you previously used a
        stash object, you can use its name, instead.  Be aware, though,
        that these (old) names and the (new) symbolic names have only a
        passing resemblance.  See "all stashes documented" below.

    - ‘#t’ means "full set" for flags

        Previously, to get the aggregate (logior) value a flagstash,
        you had to do something like:

         (define FS (flagstash:event-mask))
         (flags->number FS (flagstash-flags FS))
         => 212990 (#x33ffe)

        Now, you can use use ‘#t’ wherever you would have previously
        used ‘(flagstash-flags FLAGSTASH)’, to simplify things a bit:

         (flags->number 'event-mask #t)
         => 212990 (#x33ffe)

        Note that this example uses the symbol ‘event-mask’ instead of
        ‘flagstash:event-mask’, which is no longer available (see
        "conversion procs take stash name" and "stash objects dropped"
        above).  This "‘#t’ means full set" feature is also available
        for any proc that takes flags, not just ‘flags->number’.  E.g.:

         (evqueue-peek 99 #t)

        returns the count (<= 99) of events in the queue, matching
        against all of them.

    - [BI] ‘(sdl sdl) enumstash-enums’ dropped
    - [BI] ‘(sdl sdl) flagstash-flags’ dropped

        These are underpowered and obsoleted by ‘kotk’ (see above).

    - [BI] enums / flags names decluttered

        Several enumstashes / flagstashes have undergone name
        decluttering, basically removal of common prefix/suffix,
        conversion of ‘_’ (underscore) to ‘-’ (hyphen), and other simple
        transforms to make the symbols blend better with ambiant Scheme.
        Here is an approximate summary:

         overlay            s/^SDL_//; s/_OVERLAY$//
         font-style         s/^TTF_STYLE_//; downcase
         palette            s/^SDL_//; s/PAL$/ical/; downcase
         keyboard-modifier  s/^KMOD_//; s/^[LR]/\1-/; downcase rest
         init               s/^SDL_INIT_//; downcase; add hyphens
         event-mask         s/^SDL_//; s/MASK$//; downcase; add hyphens
         event-type         s/^SDL_//; downcase; add hyphens
         cdrom-state        downcase; add hyphens
         video              s/^SDL_//; downcase; add hyphens
         keysym             s/^SDLK_//; downcase; add hyphens; etc
                            (former name: ‘(sdl sdl) event-keys’)

        To ameliorate the pain (somewhat) of tracking these changes in
        existing code, "make install" also copies to $(pkgdatadir)/0.5 a
        set of corresponding sed scripts.  See ugh/README.

        See also "all stashes documented" below.

    - new proc: ‘(sdl sdl) surface-pixels’

        This returns a uniform vector (type u8, u16, u32) of the pixel
        data for SURFACE, or u8 unconditionally if optional arg SQUASH
        is non-‘#f’.

    - changes to "make check"

      - leak test run unconditionally

        It's not very accurate and adds a few seconds to "make check",
        but OTOH it's better to notice any weirdness earlier than later.
        Note that for Guile 2.x, this test is still skipped anyway.

      - ‘DEBUG=1’ less influential

        Previously, that option enabled certain informative output as
        well as arranging for "guile --debug" and so forth.  Now, output
        gating is affected solely by ‘VERBOSE=1’.

      - new option ‘OGGPLAYER=COMMAND’

        The mixer test (which also requires ‘INTERACTIVE=1’, btw) now
        consults env var ‘OGGPLAYER’ as well for testing external player
        support.  See README.

      - improved coverage and performance

        The count of slighted procs is now 60 (see test/t99-cov).

        Additionally, to appease the impatient, the tests run quicker
        now, in some cases due to reduced iteration counts or pause
        times, in some cases due to better-matched screen and (working)
        surface bit depths.  If your system supports MMX, this speed-up
        is most dramatic for test/gfx.scm (see also var ‘DEPTH’).

    - all stashes documented

        Appendix A documents all the stashes, describing their name, the
        count of symbols they hold, their disposition (either ‘enums’ or
        ‘flags’), and the symbols themselves.

    - bootstrap tools upgraded
      - GNU Automake 1.13.4
      - Guile-BAUX 20130705.0751.4969fb4

tarballs and detached signatures:

  http://ftpmirror.gnu.org/guile-sdl/guile-sdl-0.5.0.tar.lz
  http://ftpmirror.gnu.org/guile-sdl/guile-sdl-0.5.0.tar.lz.sig
  http://ftpmirror.gnu.org/guile-sdl/guile-sdl-0.5.0.tar.xz
  http://ftpmirror.gnu.org/guile-sdl/guile-sdl-0.5.0.tar.xz.sig

source code:

  http://git.savannah.gnu.org/cgit/guile-sdl.git/?h=p

homepage:

  http://www.gnu.org/software/guile-sdl/

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

signature.asc
Description: PGP signature