Excuses (Guile-SDL)

13 Excuses

Here are some notes on interface elements from /usr/include/SDL/*.h that are not yet wrapped by Guile-SDL. As things progress elements will be removed until an irreducible set remains.

Interface elements have zero or more attributes, some of which indicate irreducibility (such as probably-never). Following the attribute groupings are specific notes on those elements that are particular in some way. The presentation order is not significant.

Categories
Specific Notes

13.1 Categories

For brevity, we omit the SDL_ prefix in the groupings. There are two speical cases: (N) stands for SDLNet_, and (M) stands for Mix_.

internal

These interface elements are exposed in the C header but should not be exposed to Scheme, for reasons of either safety or inutility.

  SoftStretch  LowerBlit  UpperBlit
  VideoInit  VideoQuit  AudioQuit  AudioInit
  (M)GetChunk

probably-never

Don’t expect to see these exposed to Scheme, ever!

  SoftStretch  SaveBMP_RW  LoadBMP_RW
  VideoInit  VideoQuit  InitQuickDraw  RegisterApp
  SetModuleHandle  getenv  putenv
  ClearError  SetError  WriteBE64  WriteLE64
  WriteBE32  WriteLE32  WriteBE16  WriteLE16
  ReadBE64  ReadLE64  ReadBE32  ReadLE32
  ReadBE16  ReadLE16  CloseAudio  UnlockAudio
  LockAudio  MixAudio  ConvertAudio  BuildAudioCVT
  FreeWAV  LoadWAV_RW  PauseAudio  GetAudioStatus
  OpenAudio  AudioDriverName  AudioQuit
  AudioInit  (M)GetMusicHookData  (M)GetChunk

doze

Windoze support, blech.

  SaveBMP_RW  LoadBMP_RW  RegisterApp
  SetModuleHandle

threading-implications

Will (any :–) ttn ever be ready for parallelism?

  RemoveTimer  AddTimer  SetTimer  KillThread
  WaitThread  GetThreadID  ThreadID
  CreateThread  CondWaitTimeout  CondWait
  CondBroadcast  CondSignal  DestroyCond
  CreateCond  SemValue  SemPost  SemWaitTimeout
  SemTryWait  SemWait  DestroySemaphore  CreateSemaphore
  DestroyMutex  mutexV  mutexP  CreateMutex

todo

To be completed by Guile-SDL 1.0 (that is, if All Goes Well).

  KillThread  WaitThread  GetThreadID
  ThreadID  CreateThread  CondWaitTimeout
  CondWait  CondBroadcast  CondSignal
  DestroyCond  CreateCond  SemValue
  SemPost  SemWaitTimeout  SemTryWait
  SemWait  DestroySemaphore  CreateSemaphore
  DestroyMutex  mutexV  mutexP  CreateMutex
  (N)Init  (N)Quit  (N)ResolveHost  (N)ResolveIP
  (N)TCP_Open  (N)TCP_Accept  (N)TCP_GetPeerAddress
  (N)TCP_Send  (N)TCP_Recv  (N)TCP_Close
  (N)AllocPacket  (N)ResizePacket  (N)FreePacket
  (N)AllocPacketV  (N)FreePacketV  (N)UDP_Open
  (N)UDP_Bind  (N)UDP_Unbind  (N)UDP_GetPeerAddress
  (N)UDP_SendV  (N)UDP_Send  (N)UDP_RecvV
  (N)UDP_Recv  (N)UDP_Close  (N)AllocSocketSet
  (N)AddSocket  (N)DelSocket  (N)CheckSockets
  (N)SocketReady  (N)FreeSocketSet  (N)Write16
  (N)Write32  (N)Read16  (N)Read32  (M)SetPostMix
  (M)HookMusic  (M)HookMusicFinished  (M)ChannelFinished
  (M)RegisterEffect  (M)UnregisterEffect  (M)UnregisterAllEffects
  (M)SetReverb  (M)SetReverseStereo  (M)SetMusicPosition
  (M)SetSynchroValue  (M)GetSynchroValue

rwops

Read-write operations.

  FreeRW  AllocRW  RWFromMem  RWFromConstMem
  RWFromFile

macos

Macintosh support, meh.

  InitQuickDraw

endian

These concern little- vs. big-endian i/o. Perhaps Guile already provides decent alternatives.

  WriteBE64  WriteLE64  WriteBE32  WriteLE32
  WriteBE16  WriteLE16  ReadBE64  ReadLE64
  ReadBE32  ReadLE32  ReadBE16  ReadLE16

use-mixer-instead

These elements are obsoleted by the module (sdl mixer).

  CloseAudio  UnlockAudio  LockAudio
  MixAudio  ConvertAudio  BuildAudioCVT
  FreeWAV  LoadWAV_RW  PauseAudio  GetAudioStatus
  OpenAudio  AudioDriverName  AudioQuit
  AudioInit

hook

Callback from SDL to Scheme code. Can be tricky to get right...

  (M)SetPostMix  (M)HookMusic  (M)HookMusicFinished  (M)ChannelFinished
  (M)RegisterEffect  (M)UnregisterEffect  (M)UnregisterAllEffects

13.2 Specific Notes

SDL_SoftStretch

SDL_video.h sez:
/* Not in public API at the moment - do not use! */

SDL_CreateRGBSurfaceFrom

not sure what this is useful for

SDL_GL_UpdateRects

arglist: (int numrects, SDL_Rect* rects)

we can either try to map uniform vectors (of smobs),
or introduce a `RectVector' smob.

SDL_VideoInit

actually, SDL_video.h sez:
/* These functions are used internally, and should not be used unless you
 * have a specific need to specify the video driver you want to use.
 * You should normally use SDL_Init() or SDL_InitSubSystem().
 * ...
 */

SDL_VideoQuit

see note for `SDL_VideoInit'

SDL_Linked_Version

SDL_version.h sez:
/* This function gets the version of the dynamically linked SDL library.
   it should NOT be used to fill a version structure, instead you should
   use the SDL_Version() macro.
 */

SDL_GetWMInfo

return value for proc `get-wm-info' does not presently
include the `lock_func' and `unlock_func' hooks.
support for those will be added after i figure out
how to "thunkify" them.

SDL_GetKeyName

why do we want to know the name of a key?

SDL_AudioQuit

SDL_audio.h sez:
/* These functions are used internally, and should not be used unless you
 * have a specific need to specify the audio driver you want to use.
 * You should normally use SDL_Init() or SDL_InitSubSystem().
 */

SDL_AudioInit

see note for `SDL_AudioQuit'

SDLNet_AddSocket

there are also:
#define SDLNet_TCP_AddSocket
#define SDLNet_UDP_AddSocket

SDLNet_DelSocket

there are also:
#define SDLNet_TCP_DelSocket
#define SDLNet_UDP_DelSocket

Mix_GetMusicHookData

If (when) `Mix_HookMusic' is added, it will not support "user data".
It's better to use object properties for that.