--------------------------------------------------------------------- EELBox - An EEL Binding For SDL + Some Add-On Libraries --------------------------------------------------------------------- Copyright 2005-2006 David Olofson Development Code Warning ------------------------ EEL being a "true" high level scripting/programming language, it is the intention that EELBox should never crash, no matter what the EEL code executed tries to do, and that it should always handle errors in a friendly way. However... NO WARRANTY! Use this software at your own risk! EEL is a complex beast (optimizing compiler + virtual machine), and both EEL and EELBox are in early stages of development. Don't be surprised if things blow up because of seemingly harmless mistakes, or even spontaneously because of bugs in EEL or EELBox. That said, should you somehow make EEL or EELBox crash, please file a detailed bug report to the author. Crashes are not supposed to happen, ever, as long as you stick with EEL code. If they happen anyway, it's not only (if at all) your EEL code that need fixing. Introduction ------------ EELBox is an EEL binding that allows EEL code to use SDL (the Simple DirectMedia Layer), SDL_image and SDL_net. It also adds some minor tweaks and support logic to make the use of these libraries from EEL easier and faster. EELBox tries to make the wrapped APIs taste like EEL, to make them safe and easy to use in actual EEL code. As far as it makes sense, the syntax and semantics of the original C API is preserved, though in some cases, the differences between C and EEL (automatic memory management, primarily) has required some adjustments. Overview -------- EELBox is implemented as a number of native (C) modules, and an EEL helper module: Native modules: SDL The SDL binding + Plot() etc SDL_image SDL_image binding. (Image file loading) SDL_net SDL_net binding. (TCP/IP + UDP) eelbox_c Support for the "eelbox" module EEL modules: eelbox Naming Conventions ------------------ Since EEL can place the imports from a module in a named namespace, I see no need for bloating all code with prefixes. Thus, all SDL_ prefixes have been removed from function and constant names. If that makes you nervous, just make a habit of always importing the EELBox modules into a suitable namespace, such as 'eb', 'EB', 'SDL' or whatever. (The EELBox modules have no name clashes, so they should all fit in the same namespace, if desired.) The "eelbox" Module ------------------- So far, all this module provides is a function that returns an array filled in with the version of EELBox you're using: --------------------------------------------------------------------- function Version; Returns an array with thre or more elements; [0]: major version (major changes) [1]: minor version (additions only) [2]: micro version (bug fixes only) Any elements beyond index 2 are for builds and releases only, and should normally not be considered when checking versions. --------------------------------------------------------------------- The "SDL" Module ---------------- This is the main module of EELBox; the actual SDL core library wrapper. Here you'll find calls to open a display, create and manipulate surfaces, basic rendering, keyboard, joystick and mouse input and so on. --------------------------------------------------------------------- function GetTicks; Get the number of milliseconds passed since EELBox (actually, SDL) was initialized. --------------------------------------------------------------------- procedure Delay(ms); Wait 'ms' milliseconds before returning. NOTE: As opposed to the SDL C API, this version tries to guarantee that a delay value of 0 performs a thread yield, like it does on Win32, regardless of platform. --------------------------------------------------------------------- procedure Flip; If the display is double buffered with hardware page flipping, this sets up a display page flip and returns. Otherwise, it copies the rendering buffer to the screen, to make it visible. NOTE: The C API takes a surface argument, but since current versions of SDL support only one screen/window, the EELBox version does not take an argument. --------------------------------------------------------------------- (procedure Update[args];) procedure Update; Wraps SDL_UpdateRect(screen, 0, 0, 0, 0). procedure Update(rect); Makes the area of the back buffer specified by 'rect' visible on the screen. procedure Update(array_of_rects); Wraps SDL_UpdateRects(), using an EEL array for passing the rectangles. procedure Update(x, y, w, h); Wraps SDL_UpdateRect(). NOTE: All of these differ from the C API version in that they clip the rectangles to the screen surface, thus avoiding crashes if incorrect rectangles are passed. --------------------------------------------------------------------- procedure BlitSurface(src)[srcrect, dst, dstrect]; Wraps SDL_BlitSurface(). Left-out arguments are passed as NULL to the C API call. Exceptions: XWRONGTYPE: Wrong type argument. XDEVICEWRITE: No screen surface, or other problem. XEOF: Surface lost. (DirectX) --------------------------------------------------------------------- The "SDL_image" Module ---------------------- TODO The "NET2" Module -------------------- This is the networking module of EELBox, wrapping the Net2 API, which is a nice, event based layer over the SDL_net add-on library. Currently, EELBox supports only the TCP part of the Net2 API. --------------------------------------------------------------------- class IPAddress host: Host IP address (integer) port: Port (integer) --------------------------------------------------------------------- class Socket index: Net2 socket index (integer) --------------------------------------------------------------------- Event types: ERROREVENT socket: Affected socket (Socket) error: Error description (string) TCPACCEPTEVENT socket: New socket (Socket) port: Port (integer) TCPRECEIVEEVENT socket: Receiving socket (Socket) TCPCLOSEEVENT socket: Socket that was closed (Socket) UDPRECEIVEEVENT socket: Receiving socket (Socket) --------------------------------------------------------------------- function TCPAcceptOn(where); Accept connectons on 'where', which can be either an integer port number, or an IPaddress. Returns a server Socket. NOTE: You must keep at least one reference to the returned Socket for as long as you intend to keep the connection! Otherwise, the connection will be closed as soon as automatic memory management kills the Socket. Exceptions: EEL_XDEVICEOPEN: Could not set up server socket (Various system errors, such as EEL_XMEMORY.) --------------------------------------------------------------------- function TCPSend(socket)[data]; Send 'data' (any number of arguments of types that can be serialized) through 'socket', which must be a connected Socket. Returns the number of bytes sent. --------------------------------------------------------------------- function TCPRead(socket); Read from 'socket', which must be a connected socket. This function is to be used when handling a TCPRECEIVEEVENT, and should be called repeatedly until no more data is available. (Unless all data is read, there will be no further events!) Returns a dstring with the read data. --------------------------------------------------------------------- procedure TCPClose(socket); Close 'socket'. NOTE: A Socket is automatically closed when the Socket object is destroyed. This procedure is intended as a way of instantly closing a connection, even if lazy memory management should delay the destruction of the Socket after all references are gone. ---------------------------------------------------------------------