# `pymunk.pygame_util` Module

This submodule contains helper functions to help with quick prototyping using pymunk together with pygame.

Intended to help with debugging and prototyping, not for actual production use in a full application. The methods contained in this module is opinionated about your coordinate system and not in any way optimized.

class `pymunk.pygame_util.``DrawOptions`(surface)

  Bases: `pymunk.space_debug_draw_options.SpaceDebugDrawOptions`

  `DRAW_COLLISION_POINTS`

    alias of `CP_SPACE_DEBUG_DRAW_COLLISION_POINTS`

  `DRAW_CONSTRAINTS`

    alias of `CP_SPACE_DEBUG_DRAW_CONSTRAINTS`

  `DRAW_SHAPES`

    alias of `CP_SPACE_DEBUG_DRAW_SHAPES`

  `__init__`(surface)

    Draw a pymunk.Space on a pygame.Surface object.

    Typical usage:

        >>> import pymunk
        >>> import pymunk.pygame_util
        >>> surface = pygame.Surface((10,10))
        >>> s = pymunk.Space()
        >>> options = pymunk.pygame_util.DrawOptions(surface)
        >>> s.debug_draw(options)

    Since pygame uses a coordinate system where y points down (compared to most other cases where a positive y points upwards), we might want to make adjustments for that with the `positive_y_is_up` variable.

    By default drawing is done with positive y pointing up, but that will make conversion from pygame coordinate to pymunk coordinate necessary. If you do a lot of those (for example, lots of mouse input) it might be more convenient to set it to False:

        >>> positive_y_is_up = False
        >>> # Draw verything the pygame way, (0,0) in the top left corner
        >>> positive_y_is_up = True
        >>> # Draw everything the pymunk way, (0,0) in the bottom left corner

    You can control the color of a shape by setting shape.color to the color you want it drawn in.

        >>> c = pymunk.Circle(None, 10)
        >>> c.color = pygame.color.THECOLORS["pink"]

    See pygame_util.demo.py for a full example

    Parameters
      surfacepygame.Surface

        Surface that the objects will be drawn on

  `collision_point_color`

    The color of collisions.

    Should be a tuple of 4 ints between 0 and 255 (r,g,b,a).

    Example:

        >>> import pymunk
        >>> s = pymunk.Space()
        >>> b = pymunk.Body(1,10)
        >>> c1 = pymunk.Circle(b, 10)
        >>> c2 = pymunk.Circle(s.static_body, 10)
        >>> s.add(b, c1, c2)
        >>> s.step(1)
        >>> options = pymunk.SpaceDebugDrawOptions()
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=52.0, g=152.0, b=219.0, a=255.0))
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))
        draw_segment (Vec2d(8.0, 0.0), Vec2d(-8.0, 0.0), SpaceDebugColor(r=231.0, g=76.0, b=60.0, a=255.0))
        >>> options.collision_point_color = (10,20,30,40)
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=52.0, g=152.0, b=219.0, a=255.0))
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))
        draw_segment (Vec2d(8.0, 0.0), Vec2d(-8.0, 0.0), SpaceDebugColor(r=10.0, g=20.0, b=30.0, a=40.0))

  `color_for_shape`(shape)
  `constraint_color`

    The color of constraints.

    Should be a tuple of 4 ints between 0 and 255 (r,g,b,a).

    Example:

        >>> import pymunk
        >>> s = pymunk.Space()
        >>> j = pymunk.PivotJoint(s.static_body, s.static_body, (0,0))
        >>> s.add(j)
        >>> options = pymunk.SpaceDebugDrawOptions()
        >>> s.debug_draw(options)
        draw_dot (5.0, Vec2d(0.0, 0.0), SpaceDebugColor(r=142.0, g=68.0, b=173.0, a=255.0))
        draw_dot (5.0, Vec2d(0.0, 0.0), SpaceDebugColor(r=142.0, g=68.0, b=173.0, a=255.0))
        >>> options.constraint_color = (10,20,30,40)
        >>> s.debug_draw(options)
        draw_dot (5.0, Vec2d(0.0, 0.0), SpaceDebugColor(r=10.0, g=20.0, b=30.0, a=40.0))
        draw_dot (5.0, Vec2d(0.0, 0.0), SpaceDebugColor(r=10.0, g=20.0, b=30.0, a=40.0))

  `draw_circle`(pos, angle, radius, outline_color, fill_color)
  `draw_dot`(size, pos, color)
  `draw_fat_segment`(a, b, radius, outline_color, fill_color)
  `draw_polygon`(verts, radius, outline_color, fill_color)
  `draw_segment`(a, b, color)
  `flags`

    Bit flags which of shapes, joints and collisions should be drawn.

    By default all 3 flags are set, meaning shapes, joints and collisions will be drawn.

    Example using the basic text only DebugDraw implementation (normally you would the desired backend instead, such as pygame_util.DrawOptions or pyglet_util.DrawOptions):

        >>> import pymunk
        >>> s = pymunk.Space()
        >>> b = pymunk.Body()
        >>> c = pymunk.Circle(b, 10)
        >>> c.mass = 3
        >>> s.add(b, c)
        >>> s.add(pymunk.Circle(s.static_body, 3))
        >>> s.step(0.01)
        >>> options = pymunk.SpaceDebugDrawOptions()

        >>> # Only draw the shapes, nothing else:
        >>> options.flags = pymunk.SpaceDebugDrawOptions.DRAW_SHAPES
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=52.0, g=152.0, b=219.0, a=255.0))
        draw_circle (Vec2d(0.0, 0.0), 0.0, 3.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))

        >>> # Draw the shapes and collision points:
        >>> options.flags = pymunk.SpaceDebugDrawOptions.DRAW_SHAPES
        >>> options.flags |= pymunk.SpaceDebugDrawOptions.DRAW_COLLISION_POINTS
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=52.0, g=152.0, b=219.0, a=255.0))
        draw_circle (Vec2d(0.0, 0.0), 0.0, 3.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))
        draw_segment (Vec2d(1.0, 0.0), Vec2d(-8.0, 0.0), SpaceDebugColor(r=231.0, g=76.0, b=60.0, a=255.0))

  `shape_dynamic_color` = SpaceDebugColor(r=52, g=152, b=219, a=255)
  `shape_kinematic_color` = SpaceDebugColor(r=39, g=174, b=96, a=255)
  `shape_outline_color`

    The outline color of shapes.

    Should be a tuple of 4 ints between 0 and 255 (r,g,b,a).

    Example:

        >>> import pymunk
        >>> s = pymunk.Space()
        >>> c = pymunk.Circle(s.static_body, 10)
        >>> s.add(c)
        >>> options = pymunk.SpaceDebugDrawOptions()
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=44.0, g=62.0, b=80.0, a=255.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))
        >>> options.shape_outline_color = (10,20,30,40)
        >>> s.debug_draw(options)
        draw_circle (Vec2d(0.0, 0.0), 0.0, 10.0, SpaceDebugColor(r=10.0, g=20.0, b=30.0, a=40.0), SpaceDebugColor(r=149.0, g=165.0, b=166.0, a=255.0))

  `shape_sleeping_color` = SpaceDebugColor(r=114, g=148, b=168, a=255)
  `shape_static_color` = SpaceDebugColor(r=149, g=165, b=166, a=255)

`pymunk.pygame_util.``get_mouse_pos`(surface)

  Get position of the mouse pointer in pymunk coordinates.

`pymunk.pygame_util.``to_pygame`(p, surface)

  Convenience method to convert pymunk coordinates to pygame surface local coordinates.

  Note that in case positive_y_is_up is False, this function wont actually do anything except converting the point to integers.

`pymunk.pygame_util.``from_pygame`(p, surface)

  Convenience method to convert pygame surface local coordinates to pymunk coordinates

`pymunk.pygame_util.``positive_y_is_up` = True

  Make increasing values of y point upwards.

  When True:

          y
          ^
          |   . (2, 2)
          |
      ----+------ > x
          |
          |     . (3, -2)
          |

  When False:

          y
          ^
          |   . (2, -2)
          |
      ----+------ > x
          |
          |      . (3, 2)
          |