Index

1. Programming Proverbs

• 19. ‘‘Prettyprint - format your code so that it looks nice.’’
• Henry F. Ledgard, ‘‘Programming Proverbs: Principles of Good Programming with Numerous Examples to Improve Programming Style and Proficiency’’, (Hayden Computer Programming Series), Hayden Book Company, 1st edition, ISBN-13: 978-0810455221, December 1975.

2. PGE, libtool and passing aggregate data between Python/C++

• examine the file pge/c/Makefile.am
  • notice the rule starting with the text
  • libpgeif.la: this rule generates the library libpgeif.la using a variant of the command given on the previous slides

• swig -outdir . -o pgeif_wrap.cxx -c++ -python $(top_srcdir)/i/pgeif.i
  $(LIBTOOL) --tag=CC --mode=compile g++ -g -c pgeif_wrap.cxx \
    -I/usr/include/python$(PYTHON_VERSION) -o pgeif_wrap.lo
  gm2 -c -g -I$(SRC_PATH_PIM) -fcpp -fmakelist \
    -I$(top_srcdir)/m2 $(top_srcdir)/m2/pgeif.mod
  gm2 -c -g -I$(SRC_PATH_PIM) -fcpp -fmakeinit -fshared \
    -I$(top_srcdir) $(top_srcdir)/m2/pgeif.mod
  $(LIBTOOL) --tag=CC $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) \
    --mode=compile gcc -c $(CFLAGS_FOR_TARGET) $(LIBCFLAGS) \
    $(libgm2_la_M2FLAGS) $(srcdir)/pgeif.c -o pgeif.lo
  $(LIBTOOL) --tag=CC --mode=compile g++ -g -c _m2_pgeif.cpp -o _m2_pgeif.lo
  $(LIBTOOL) --tag=CC --mode=link gcc -g _m2_pgeif.lo $(MY_DEPS) \
      pgeif_wrap.lo \
     -L$(GM2LIBDIR)/lib64 \
     -rpath ‘pwd‘ -liso -lgcc -lstdc++ -lpth -lc -lm -o libpgeif.la
  cp .libs/libpgeif.so ../_pgeif.so
  cp pgeif.py ../pgeif.py

3. More complex example

• passing data from Python into C, C++, Modula-2 shared library
  • can pass int , float , double and enums easily enough
• strings are also reasonably well supported
• how do we pass aggregate data types between Python and C/C++?
  • how do we return aggregate from C/C++ into Python?

4. Aggregate data types

• an aggregate data type is a data type which contains different sub types
  • for example a struct containing an int and a char field

• typedef struct aggregate_t {
    int field1;
    char field2;
  } aggregate;

5. Passing aggregate data types from Python into C/C++

• fortunately binary strings of data can be passed between Python and C/C++ using swig
• we can build a sequence of bytes using the Python struct module
  • the struct module uses a printf formatting structure to pack and unpack binary data

6. Why do we need to pass aggregate data types from C/C++ to Python?

• consider, pge , the shared library module generate events which might be:
  • a draw frame event
  • a collision event
  • a timer event
• the draw frame event
  • contains a list of polygons and circles and their position and colour which need to be rendered to represent the world
  • this is a dynamic list of objects containing many different data types
• a collision event
  • contains the time of collision, position of the collision
  • and the object id s in collision
• this will be a fixed aggregate structure of known length
• the timer event will have a time field ( double ) and the timer id ( integer ) as well as a few other fields
  • this is also fixed in length and represented in C as a struct

7. Passing aggregate data from C, C++, Modula-2 into Python

• we can use the string passing mechanism to pass bytes
  • the .i file needs extra information to say which functions return binary data and also that the shared library can set the length

• pge/i/pgeif.i

  ...
  %include cstring.i
  %cstring_output_allocate_size(char **s, int *slen, );
  
  
  %{
  extern "C" void get_cbuf (char **s, int *slen);
  extern "C" void get_ebuf (char **s, int *slen);
  extern "C" void get_fbuf (char **s, int *slen);
  ...

• notice that a Python string is created in the shared library and passed back to the Python caller
• also notice that get_cbuf is a function!
  • returning a string
• the swig information

• %include cstring.i
  %cstring_output_allocate_size(char **s, int *slen, );

• indicates these types and name match a return string allocated in the shared library
• 
  pge/python/pge.py

  def runbatch (t):
      if t < 0.0:
          t = 30.0
      _debugf ("runbatch (%f)\n", t)
      pgeif.check_objects ()
      cData = pgeif.get_cbuf ()
      fData = pgeif.get_fbuf ()
      _draw_frame (cData, len (cData), fData, len (fData))
      pgeif.empty_fbuffer ()
      pgeif.empty_cbuffer ()

• swig has many mechanisms to allow binary strings of data to be retrieved
  • above is the safest - as it contains the length
    

8. PGE structure

9. Passing aggregate data from C, C++, Modula-2 into Python

• examine the function _draw_frame which calls the function

• pge/python/pge.py

  #
  #  _pyg_draw_frame - draws a frame on the pygame display.
  #
  
  
  def _pyg_draw_frame (cdata, clength, fdata, flength):
      global nextFrame, call, _record

• 
  pge/python/pge.py

      if _record:
          _begin_record_frame (cdata, clength, fdata, flength)
      elif flength > 0:
          _draw_background ()
      f = _myfile (cdata + fdata)
      while f.left () >= 3:
          header = struct.unpack ("3s", f.read (3))[0]
          header = header[:2]
          if call.has_key (header):
              f = call[header] (f)
          else:
              print "not understood header =", header
              sys.exit (1)

• 
  pge/python/pge.py

      if flength > 0:
          _draw_foreground ()
      if _record:
          _end_record_frame ()
      if flength > 0:
          _doFlipBuffer ()  # flipping the buffer for an empty frame looks ugly
      nextFrame += 1
      _debugf ("moving onto frame %d\n", nextFrame)

10. Inside the shared library

• it creates the byte string containing aggregate data

• pge/c/buffers.c

  /*
   *  buffers - wrap the event buffer contents into a binary string.
   */
  
  extern void deviceIf_getFrameBuffer (void **start,
                                       int *length, int *used);
  
  
  void get_fbuf (void **start, unsigned int *used)
  {
    int length;
  #if !defined (DEBUGGING)
    printf ("calling deviceIf_getFrameBuffer\n");
  #endif
    deviceIf_getFrameBuffer (start, &length, used);
  }

• examine the file pge/c/deviceIf.c
  • follow the functions: deviceIf_emptyFbuffer , deviceIf_useBuffer and deviceIf_finish
• notice the use of the module MemStream
  • read the documentation of MemStream http://nongnu.org/gm2/gm2-libs-isomemstream.html
• MemStream allows the caller to use file operations to maintain a byte string which is contiguous and held in memory
  

11. Conclusion and pgeif.i

• the full API describing the C interface is described in pge/i/pgeif.i
  • examine this file and see how a circle , colour and box are created
• now read the file pge/python/pge.py and see how a call to box and colour is mapped into the pgeif.i calls

Index

This document was produced using groff-1.22.