Anonymous avatar Anonymous committed 30436d9

Documented struct classes.

Comments (0)

Files changed (13)

  - SDL_WM_SetCaption and SDL_WM_GetCaption accept and return Unicode strings.
  - Removed SDL_opengl.h from SDL.constants
  - Added SDL_CreateCursor.
+ - Documented struct classes
 
 SDL-ctypes 0.04
 ---------------
     CFUNCTYPE(POINTER(c_ubyte), POINTER(c_ubyte), POINTER(c_ubyte), c_int)
 
 class SDL_AudioSpec(Structure):
+    '''Audio format structure.
+
+    The calculated values in this structure are calculated by `SDL_OpenAudio`.
+
+    :Ivariables:
+        `freq` : int
+            DSP frequency, in samples per second
+        `format` : int
+            Audio data format. One of AUDIO_U8, AUDIO_S8, AUDIO_U16LSB,
+            AUDIO_S16LSB, AUDIO_U16MSB or AUDIO_S16MSB
+        `channels` : int
+            Number of channels; 1 for mono or 2 for stereo.
+        `silence` : int
+            Audio buffer silence value (calculated)
+        `samples` : int
+            Audio buffer size in samples (power of 2)
+        `size` : int
+            Audio buffer size in bytes (calculated)
+
+    '''
     _fields_ = [('freq', c_int),
                 ('format', c_ushort),
                 ('channels', c_ubyte),
                 ('silence', c_ubyte),
                 ('samples', c_ushort),
-                ('padding', c_ushort),
+                ('_padding', c_ushort),
                 ('size', c_uint),
                 ('_callback', _SDL_AudioSpec_fn),
                 ('_userdata', c_void_p)]
     CFUNCTYPE(POINTER(c_ubyte), _SDL_AudioCVT_p, c_ushort)
 
 class SDL_AudioCVT(Structure):
+    '''Set of audio conversion filters and buffers.
+
+    :Ivariables:
+        `needed` : int
+            1 if conversion is possible
+        `src_format` : int
+            Source audio format.  See `SDL_AudioSpec.format`
+        `dst_format` : int
+            Destination audio format.  See `SDL_AudioSpec.format`
+        `rate_incr` : float
+            Rate conversion increment
+        `len` : int
+            Length of original audio buffer
+        `len_cvt` : int
+            Length of converted audio buffer
+        `len_mult` : int
+            Buffer must be len * len_mult big
+        `len_ratio` : float
+            Given len, final size is len * len_ratio
+        `filter_index` : int
+            Current audio conversion function
+        
+    '''
     _fields_ = [('needed', c_int),
                 ('src_format', c_ushort),
                 ('dst_format', c_ushort),
 # end enum CDstatus
 
 class SDL_CDtrack(Structure):
+    '''Structure describing a single CD track.
+
+    :Ivariables:
+        `id` : int
+            Track number
+        `type` : int
+            One of SDL_AUDIO_TRACK or SDL_DATA_TRACK
+        `length` : int
+            Length, in frames, of this track
+        `offset` : int
+            Offset, in frames, from start of disk
+
+    '''
     _fields_ = [('id', c_ubyte),
                 ('type', c_ubyte),
                 ('_unused', c_ushort),
                 ('offset', c_uint)]
 
 class SDL_CD(Structure):
+    '''Structure describing a CD.
+
+    This structure is only current as of the last call to `SDL_CDStatus`.
+
+    :Ivariables:
+        `id` : int
+            Private drive identifier
+        `status` : int
+            Current drive status.  One of CD_TRAYEMPTY, CD_STOPPED,
+            CD_PLAYING, CD_PAUSED, CD_ERROR.
+        `numtracks` : int
+            Number of tracks on disk
+        `cur_track` : int
+            Current track position
+        `cur_frame` : int
+            Current frame offset within current track
+        `track` : sequence of `SDL_CDtrack`
+            Tracks on the disk.
+
+    '''
     _fields_ = [('id', c_uint),
                 ('status', c_int),
                 ('numtracks', c_int),
     SDL_GETEVENT) = range(3)
 
 class SDL_ActiveEvent(Structure):
+    '''Application visibility event structure.
+
+    :see: `SDL_GetAppState`
+
+    :Ivariables:
+        `type` : int
+            SDL_ACTIVEEVENT
+        `gain` : int
+            1 if states were gained, zero otherwise
+        `state` : int
+            A mask of the focus states.  A bitwise OR combination of:
+            SDL_APPMOUSEFOCUS, SDL_APPINPUTFOCUS and SDL_APPACTIVE.
+
+    '''
     _fields_ = [('type', c_ubyte),
                 ('gain', c_ubyte),
                 ('state', c_ubyte)]
 
 class SDL_KeyboardEvent(Structure):
+    '''Keyboard event structure.
+
+    :Ivariables:
+        `type` : int
+            SDL_KEYDOWN or SDL_KEYUP
+        `which` : int
+            The keyboard device index
+        `state` : int
+            SDL_PRESSED or SDL_RELEASED
+        `keysym` : `SDL_keysym`
+            Decoded key information.
+
+    '''
     _fields_ = [('type', c_ubyte),
                 ('which', c_ubyte),
                 ('state', c_ubyte),
                 ('keysym', SDL.keyboard.SDL_keysym)]
 
 class SDL_MouseMotionEvent(Structure):
+    '''Mouse motion event structure.
+
+    :Ivariables:
+        `type` : int
+            SDL_MOUSEMOTION
+        `which` : int
+            The mouse device index
+        `state` : int
+            The current button state
+        `x` : int
+            The X coordinate of the mouse pointer
+        `y` : int
+            The Y coordinate of the mouse pointer
+        `xrel` : int
+            The relative motion in the X direction
+        `yrel` : int
+            The relative motion in the Y direction
+
+    '''
     _fields_ = [('type', c_ubyte),
                 ('which', c_ubyte),
                 ('state', c_ubyte),
                 ('yrel', c_short)]
 
 class SDL_MouseButtonEvent(Structure):
+    '''Mouse button event structure.
+
+    :Ivariables:
+        `type` : int
+            SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP
+        `which` : int
+            The mouse device index
+        `button` : int
+            The mouse button index
+        `state` : int
+            SDL_PRESSED or SDL_RELEASED
+        `x` : int
+            The X coordinate of the mouse pointer
+        `y` : int
+            The Y coordinate of the mouse pointer
+    
+    '''
     _fields_ = [('type', c_ubyte),
                 ('which', c_ubyte),
                 ('button', c_ubyte),
                 ('y', c_ushort)]
 
 class SDL_JoyAxisEvent(Structure):
+    '''Joystick axis motion event structure.
+
+    :Ivariables:
+        `type` : int
+            SDL_JOYAXISMOTION
+        `which` : int
+            The joystick device index
+        `axis` : int
+            The joystick axis index
+        `value` : int
+            The axis value, in range [-32768, 32767]
+    
+    '''
     _fields_ = [('type', c_ubyte),
                 ('which', c_ubyte),
                 ('axis', c_ubyte),
                 ('value', c_short)]
 
 class SDL_JoyBallEvent(Structure):
+    '''Joystick trackball motion event structure.
+
+    :Ivariables:
+        `type` : int
+            SDL_JOYBALLMOTION
+        `which` : int
+            The joystick device index
+        `ball` : int
+            The joystick trackball index
+        `xrel` : int
+            The relative motion in the X direction
+        `yrel` : int
+            The relative motion in the Y direction
+    
+    '''
     _fields_ = [('type', c_ubyte),
                 ('which', c_ubyte),
                 ('ball', c_ubyte),
                 ('yrel', c_short)]
 
 class SDL_JoyHatEvent(Structure):
+    '''Joystick hat position change event structure.
+
+    :Ivariables:
+        `type` : int
+            SDL_JOYHATMOTION
+        `which` : int
+            The joystick device index
+        `hat` : int
+            The joystick hat index
+        `value` : int
+            The hat position value.  One of: SDL_HAT_LEFTUP, SDL_HAT_UP,
+            SDL_HAT_RIGHTUP, SDL_HAT_LEFT, SDL_HAT_CENTERED, SDL_HAT_RIGHT,
+            SDL_HAT_LEFTDOWN, SDL_HAT_DOWN, SDL_HAT_RIGHTDOWN.  Note that
+            zero means the POV is centered.
+    
+    '''
     _fields_ = [('type', c_ubyte),
                 ('which', c_ubyte),
                 ('hat', c_ubyte),
                 ('value', c_ubyte)]
 
 class SDL_JoyButtonEvent(Structure):
+    '''Joystick button event structure.
+
+    :Ivariables:
+        `type` : int
+            SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP
+        `which` : int
+            The joystick device index
+        `button` : int
+            The joystick button index
+        `state` : int
+            SDL_PRESSED or SDL_RELEASED
+
+    '''
     _fields_ = [('type', c_ubyte),
                 ('which', c_ubyte),
                 ('button', c_ubyte),
                 ('state', c_ubyte)]
 
 class SDL_ResizeEvent(Structure):
+    '''The window resized event structure.
+
+    :Ivariables:
+        `type` : int
+            SDL_VIDEORESIZE
+        `w` : int
+            New width
+        `h` : int
+            New height
+    
+    '''
     _fields_ = [('type', c_ubyte),
                 ('w', c_int),
                 ('h', c_int)]
 
 class SDL_ExposeEvent(Structure):
+    '''The screen redraw event structure.
+
+    :Ivariables:
+        `type` : int
+            SDL_VIDEOEXPOSE
+    
+    '''
     _fields_ = [('type', c_ubyte)]
 
 class SDL_QuitEvent(Structure):
+    '''The quit requested event structure
+
+    :Ivariables:
+        `type` : int
+            SDL_QUIT
+    
+    '''
     _fields_ = [('type', c_ubyte)]
 
 class SDL_UserEvent(Structure):
+    '''A user-defined event structure.
+
+    :Ivariables:
+        `type` : int
+            SDL_USEREVENT through SDL_NUMEVENTS - 1
+        `code` : int
+            User defined event code
+    
+    '''
     _fields_ = [('type', c_ubyte),
                 ('code', c_int),
                 ('data1', c_void_p),
                 ('data2', c_void_p)]
 
 class SDL_SysWMEvent(Structure):
+    '''System window management event structure.
+
+    :Ivariables:
+        `type` : int
+            SDL_SYSWMEVENT
+    
+    '''
     _fields_ = [('type', c_ubyte),
                 ('msg', c_void_p)]  # TODO with SDL_syswm.h
 
 class SDL_Event(Union):
+    '''Union event structure.
+
+    Events returned from functions are always returned as the
+    specialised subclass; for example you will receive a
+    `SDL_MouseMotionEvent` rather than `SDL_Event`.  This structure
+    therefore has limited application use, but is used internally.
+
+    :Ivariables:
+        `type` : int
+            Type of event
+    
+    '''
     _fields_ = [('type', c_ubyte),
                 ('active', SDL_ActiveEvent),
                 ('key', SDL_KeyboardEvent),
         return 'SDLEvent(type=%d)' % self.type
 
     def specialize(self):
+        '''Get an instance of the specialized subclass for this event,
+        based on `self.type`.
+
+        :rtype: `SDL_Event` subclass
+        '''
         if self.type in self.types:
             return getattr(self, self.types[self.type][1])
         elif self.type >= SDL_USEREVENT:    # SDL_MAXEVENTS not defined
 import SDL.constants
 import SDL.dll
 
-class SDL_Joystick(Structure):
+class _SDL_Joystick(Structure):
     _fields_ = [('_dummy', c_void_p)]
 
-SDL_Joystick_p = POINTER(SDL_Joystick)
+SDL_Joystick_p = POINTER(_SDL_Joystick)
 
 SDL_NumJoysticks = SDL.dll.function('SDL_NumJoysticks',
     '''Count the number of joysticks attached to the system.
         * The `unicode` translated character is only available when character
           translation is enabled by `SDL_EnableUNICODE`.  If non-empty, this is
           unicode string of unit length.
+
+    :Ivariables:
+        `scancode` : int
+            Hardware specific scancode
+        `sym` : int
+            SDL virtual keysym (SDLK_*)
+        `mod` : int
+            Bitwise OR of current key modifiers
+        `unicode` : string
+            Unicode character represented by keypress, or the empty string
+            if translation is not possible.
+
     '''
     _fields_ = [('scancode', c_ubyte),
                 ('sym', c_int),
     require_return=True)
 
 class Mix_Chunk(Structure):
+    '''Internal format for an audio chunk.
+
+    :Ivariables:
+        `allocated` : int
+            Undocumented.
+        `abuf` : `SDL_array`
+            Buffer of audio data
+        `alen` : int
+            Length of audio buffer
+        `volume` : int
+            Per-sample volume, in range [0, 128]
+
+    '''
     _fields_ = [('allocated', c_int),
                 ('_abuf', POINTER(c_ubyte)),
                 ('alen', c_uint),
 import SDL.video
 
 class SDL_Cursor(Structure):
+    '''Cursor structure.
+
+    :Ivariables:
+        `area` : `SDL_Rect`
+            Area of the mouse cursor
+        `hot_x` : int
+            X coordinate of the tip of the cursor
+        `hot_y` : int
+            Y coordinate of the tip of the cursor
+    
+    '''
     _fields_ = [('area', SDL.video.SDL_Rect),
                 ('hot_x', c_short),
                 ('hot_y', c_short),
                 ('stop', c_void_p)]
 
 class SDL_RWops(Structure):
+    '''Read/write operations structure.
+
+    :Ivariables:
+        `seek` : function
+            seek(context: `SDL_RWops`, offset: int, whence: int) -> int
+        `read` : function
+            read(context: `SDL_RWops`, ptr: c_void_p, size: int, maxnum: int) 
+            -> int
+        `write` : function
+            write(context: `SDL_RWops`, ptr: c_void_p, size: int, num: int) ->
+            int
+        `close` : function
+            close(context: `SDL_RWops`) -> int
+        `type` : int
+            Undocumented
+
+    '''
     _fields_ = [('seek', _seek_fn),
                 ('read', _read_fn),
                 ('write', _write_fn),
 import SDL.dll
 
 class SDL_version(Structure):
+    '''Version structure.
+
+    :Ivariables:
+        `major` : int
+            Major version number
+        `minor` : int
+            Minor version number
+        `patch` : int
+            Patch revision number
+
+    '''
     _fields_ = [('major', c_ubyte),
                 ('minor', c_ubyte),
                 ('patch', c_ubyte)]
 import SDL.rwops
 
 class SDL_Rect(Structure):
+    '''Rectangle structure.
+
+    Rectangles must be normalised, i.e., with their width and height
+    greater than zero.
+
+    :Ivariables:
+        `x` : int
+            Top-left x coordinate.
+        `y` : int
+            Top-left y coordinate.
+        `w` : int
+            Width
+        `h` : int
+            Height
+
+    '''
+
     _fields_ = [('x', c_short),
                 ('y', c_short),
                 ('w', c_ushort),
     '''Structure defining a single color.
 
     ``SDL_Colour`` is a synonym for ``SDL_Color``.
+
+    :Ivariables:
+        `r` : int
+            Red component, in range [0,255]
+        `g` : int
+            Green component, in range [0,255]
+        `b` : int
+            Blue component, in range [0,255]
+
     '''
     _fields_ = [('r', c_ubyte),
                 ('g', c_ubyte),
 SDL_Colour = SDL_Color
 
 class SDL_Palette(Structure):
+    '''Color palette array.
+
+    :Ivariables:
+        `ncolors` : int
+            Number of colors in the palette
+        `colors` : `SDL_array`
+            Array of indexed colors of type `SDL_Color`.
+
+    '''
     _fields_ = [('ncolors', c_int),
                 ('_colors', POINTER(SDL_Color))]
 
         
 
 class SDL_PixelFormat(Structure):
-    '''Read-only structure.
+    '''Read-only surface format structure.
+
+    :Ivariables:
+        `BitsPerPixel` : int
+            Number of bits per pixel
+        `BytesPerPixel` : int
+            Number of bytes per pixel.  This is not necessarily 8 *
+            BitsPerPixel.
+        `Rloss` : int
+            Number of bits lost from an 8-bit red component
+        `Gloss` : int
+            Number of bits lost from an 8-bit green component
+        `Bloss` : int
+            Number of bits lost from an 8-bit blue component
+        `Aloss` : int
+            Number of bits lost from an 8-bit alpha component
+        `Rshift` : int
+            Number of bits to shift right red component when packing
+        `Gshift` : int
+            Number of bits to shift right green component when packing
+        `Bshift` : int
+            Number of bits to shift right blue component when packing
+        `Ashift` : int
+            Number of bits to shift right alpha component when packing
+        `Rmask` : int
+            32-bit mask of red component
+        `Gmask` : int
+            32-bit mask of green component
+        `Bmask` : int
+            32-bit mask of blue component
+        `Amask` : int
+            32-bit mask of alpha component
+        `colorkey` : int
+            Packed transparent color key, if set.
+        `alpha` : int
+            Surface alpha, in range [0, 255]
+
     '''
     _fields_ = [('_palette', POINTER(SDL_Palette)),
                 ('BitsPerPixel', c_ubyte),
         raise AttributeError
 
 class SDL_Surface(Structure):
-    '''Read-only structure.
+    '''Read-only surface structure.
+
+    :Ivariables:
+        `format` : `SDL_PixelFormat`
+            Pixel format used by this surface
+        `w` : int
+            Width
+        `h` : int
+            Height
+        `pitch` : int
+            Number of pixel-sized elements between consecutive rows of pixel
+            data.  Note that this may be larger than the width.
+        `pixels` : SDL_array
+            Buffer of integers of the type given in the pixel format. 
+            Each element of the array corresponds to exactly one pixel
+            when ``format.BitsPerPixel`` is at least 8; otherwise each
+            element is exactly one byte.  Modifying this array has an
+            immediate effect on the pixel data of the surface.  See
+            `SDL_LockSurface`.
+
     '''
     _fields_ = [('flags', c_uint),
                 ('_format', POINTER(SDL_PixelFormat)),
                 ('h', c_int),
                 ('pitch', c_short),
                 ('_pixels', POINTER(c_ubyte)),
-                ('offset', c_int),
-                ('hwdata', c_void_p),
-                ('clip_rect', SDL_Rect),
-                ('unused1', c_int),
-                ('locked', c_int),
-                ('map', c_void_p),  # SDL_BliptMap
-                ('format_version', c_int),
-                ('refcount', c_int)]
+                ('_offset', c_int),
+                ('_hwdata', c_void_p),
+                ('_clip_rect', SDL_Rect),
+                ('_unused1', c_int),
+                ('_locked', c_int),
+                ('_map', c_void_p),  
+                ('_format_version', c_int),
+                ('_refcount', c_int)]
 
     def __getattr__(self, name):
         if name == 'format':
             if not self._pixels:
                 raise SDL.error.SDL_Exception, 'Surface needs locking'
             bpp = self.format.BitsPerPixel
-            # Can't rely on BytesPerPixel when calcaulating pitch
+            # Can't rely on BytesPerPixel when calculating pitch
             byte_pitch = self.pitch  * 8 / bpp
             count = byte_pitch * self.h
             if bpp == 1:
 class SDL_VideoInfo(Structure):
     '''Useful for determining the video hardware capabilities.
 
-    Fields current_w and current_h since 1.2.10.
+    :Ivariables:
+        `hw_available` : bool
+            True if hardware surfaces can be created
+        `wm_available` : bool
+            True if a window manager is available
+        `blit_hw` : bool
+            True if hardware to hardware blits are accelerated
+        `blit_hw_CC` : bool
+            True if hardware to hardware color-keyed blits are accelerated
+        `blit_hw_A` : bool
+            True if hardware to hardware alpha-blended blits are accelerated
+        `blit_sw` : bool
+            True if software to hardware blits are accelerated
+        `blit_sw_CC` : bool
+            True if software to hardware color-keyed blits are accelerated
+        `blit_sw_A` : bool
+            True if software to hardware alpha-blended blits are accelerated
+        `blit_fill` : bool
+            True if color fills are accelerated
+        `video_mem` : int
+            Total amount of video memory, in kilobytes (unreliable)
+        `vfmt` : `SDL_PixelFormat`
+            Pixel format of the video surface
+        `current_w` : int
+            Current video width.  Available in SDL 1.2.10 and later.
+        `current_h` : int
+            Current video height.  Available in SDL 1.2.10 and later.
+
     '''
     _fields_ = [('bitfield', c_uint),
                 ('video_mem', c_uint),
 
 class SDL_Overlay(Structure):
     '''The YUV hardware video overlay.
+
+    :Ivariables:
+        `format` : int
+            Overlay pixel layout.  One of SDL_YV12_OVERLAY, SDL_IYUV_OVERLAY,
+            SDL_YUY2_OVERLAY, SDL_UYVY_OVERLAY, SDL_YVYU_OVERLAY.
+        `w` : int
+            Width of the overlay.
+        `h` : int
+            Height of the overlay.
+        `planes` : int
+            Number of planes of pixel data.
+        `pitches` : list of int
+            List of pitches for each plane.
+        `pixels` : list of `SDL_array`
+            List of pixel buffers, one for each plane.  All pixel buffers
+            provided as byte buffers.
+
     '''
     _fields_ = [('format', c_uint),
                 ('w', c_int),
 search TODO FIXME XXX
 struct/field docstrings
-drop opengl.h from constants.py
-SetCaption unicode
-byte swapping in array, esp for audio
-endian check, e.g. for overlay and gl tests
 glitch in upper-left corner of testoverlay2 on linux; on ppc os x large
   corruption in top half
+joystick not receiving events?
+wrap SDL_sound
 
 SDL_syswm.h - platform dependent
 

support/prep_doc.py

 modules = {}
 done_modules = []
 
-def write_function(func, file):
-    if hasattr(func, '__doc__'):
+def write_function(func, file, indent=''):
+    if hasattr(func, '__doc__') and func.__doc__:
         docstring = func.__doc__
     else:
         docstring = ''
         args = args[:nondefault] + \
             ['%s=%s' % (args[i+nondefault], defaults[i]) \
                 for i in range(len(defaults))]
-    print >> file, 'def %s(%s):' % (func.__name__, ','.join(args))
-    print >> file, "    '''%s'''" % docstring
+    print >> file, '%sdef %s(%s):' % (indent, func.__name__, ','.join(args))
+    print >> file, "%s    '''%s'''" % (indent, docstring)
     print >> file
 
 def write_class(cls, file):
        ctypes.Union in cls.__bases__:
         print >> file, 'class %s:' % cls.__name__
         print >> file, '    %s' % repr(cls.__doc__ or '')
-        for field in cls._fields_:
-            if field[0] != '_':
-                print >> file, '    %s = None' % field[0]
+        for func in dir(cls):
+            if func[0] == '_' and \
+               (func[:2] != '__' or func in ('__getattr__', '__setattr__')):
+                continue
+            func = getattr(cls, func)
+            if inspect.ismethod(func):
+                write_function(func, file, '    ')
+
+        #for field in cls._fields_:
+        #    if field[0] != '_':
+        #        print >> file, '    %s = None' % field[0]
     else:
         print >> file, '%s' % inspect.getsource(cls)
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.