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
_______________________________________________ GNU Announcement mailing list <info-gnu@gnu.org> https://lists.gnu.org/mailman/listinfo/info-gnu
