# cocos.director module

cocos.director.director is the singleton that creates and handles the main `Window` and manages the logic behind the `Scenes`.

## Initializing

The first thing to do, is to initialize the `director`:

    from cocos.director import director
    director.init( parameters )

This will initialize the director, and will create a display area (a 640x480 window by default). The parameters that are supported by director.init() are the same parameters that are supported by pyglet.window.Window(), plus a few cocos exclusive ones. They are all named parameters (kwargs). See `Director.init()` for details.

Example:

    director.init( width=800, height=600, caption="Hello World", fullscreen=True )

## Running a Scene

Once you have initialized the director, you can run your first `Scene`:

    director.run( Scene( MyLayer() ) )

This will run a scene that has only 1 layer: `MyLayer()`. You can run a scene that has multiple layers. For more information about `Layers` and `Scenes` refer to the `Layers` and `Scene` documentation.

Once a scene is running you can do the following actions:

> - `director.replace( new_scene ):`

>     Replaces the running scene with the new_scene You could also use a transition. For example: director.replace( SplitRowsTransition( new_scene, duration=2 ) )

> - `director.push( new_scene ):`

>     The running scene will be pushed to a queue of scenes to run, and new_scene will be executed.

> - `director.pop():`

>     Will pop out a scene from the queue, and it will replace the running scene.

> - `director.scene.end( end_value ):`

>     Finishes the current scene with an end value of `end_value`. The next scene to be run will be popped from the queue.

Other functions you can use are:

> - `director.get_window_size():` Returns an (x,y) pair with the _logical_ dimensions of the display. The display might have been resized, but coordinates are always relative to this size. If you need the _physical_ dimensions, check the dimensions of `director.window`
> - `get_virtual_coordinates(self, x, y):` Transforms coordinates that belongs the real (physical) window size, to the coordinates that belongs to the virtual (logical) window. Returns an x,y pair in logical coordinates.

The director also has some useful attributes:

> - `director.return_value`: The value returned by the last scene that called `director.scene.end`. This is useful to use scenes somewhat like function calls: you push a scene to call it, and check the return value when the director returns control to you.
> - `director.window`: This is the pyglet window handled by this director, if you happen to need low level access to it.
> - `self.show_FPS`: You can set this to a boolean value to enable, disable the framerate indicator.
> - `self.scene`: The scene currently active

class `Director`

  Bases: `pyglet.event.EventDispatcher`

  Class that creates and handle the main Window and manages how and when to execute the Scenes

  You should not directly instantiate the class, instead you do:

      from cocos.director import director

  to access the only one Director instance.

  `get_virtual_coordinates`(x, y)

    Transforms coordinates that belongs the real window size, to the coordinates that belongs to the virtual window.

    For example, if you created a window of 640x480, and it was resized to 640x1000, then if you move your mouse over that window, it will return the coordinates that belongs to the newly resized window. Probably you are not interested in those coordinates, but in the coordinates that belongs to your virtual window.

    Return type: | (x,y)
    Returns: | Transformed coordinates from the real window to the virtual window

  `get_window_size`()

    Returns the size of the window when it was created, and not the actual size of the window.

    Usually you don’t want to know the current window size, because the Director() hides the complexity of rescaling your objects when the Window is resized or if the window is made fullscreen.

    If you created a window of 640x480, the you should continue to place your objects in a 640x480 world, no matter if your window is resized or not. Director will do the magic for you.

    Return type: | (x,y)
    Returns: | The size of the window when it was created

  `init`(*args, **kwargs)

    Initializes the Director creating the main window.

    There are a few cocos exclusive parameters, the rest are the standard pyglet parameters for pyglet.window.Window.__init__ This docstring only partially list the pyglet parameters; a full list is available at pyglet Window API Reference at http://pyglet.org/doc/api/pyglet.window.Window-class.html

    Parameters: | autoscale : bool True: on window resizes, cocos will scale the view so that your app don’t need to handle resizes. False: your app must include logic to deal with different window sizes along the session. Defaults to False do_not_scale : bool Deprecated. The logical negation of autoscale audio_backend : string one in [‘pyglet’,’sdl’]. Defaults to ‘pyglet’ for legacy support. audio : dict or None None or a dict providing parameters for the sdl audio backend. None: in this case a “null” audio system will be used, where all the sdl sound operations will be no-ops. This may be useful if you do not want to depend on SDL_mixer A dictionary with string keys; these are the arguments for setting up the audio output (sample rate and bit-width, channels, buffer size). The key names/values should match the positional arguments of http://www.pygame.org/docs/ref/mixer.html#pygame.mixer.init The default value is {}, which means sound enabled with default settings fullscreen : bool Window is created in fullscreen. Default is False resizable : bool Window is resizable. Default is False vsync : bool Sync with the vertical retrace. Default is True width : int Window width size. Default is 640 height : int Window height size. Default is 480 caption : string Window title. visible : bool Window is visible or not. Default is True.
    Return type: | pyglet.window.Window
    Returns: | The main window, an instance of pyglet.window.Window class.

  `on_draw`()

    Handles the event ‘on_draw’ from the pyglet.window.Window

    Realizes switch to other scene and app termination if needed Clears the window area The windows is painted as:

    > - Render the current scene by calling it’s visit method
    > - Eventually draw the fps metter
    > - Eventually draw the interpreter

    When the window is minimized any pending switch to scene will be delayed to the next de-minimizing time.

  `on_pop`()
  `on_push`(scene)
  `pop`()

    If the scene stack is empty the appication is terminated. Else pops out a scene from the stack and sets as the running one.

  `push`(scene)

    Suspends the execution of the running scene, pushing it on the stack of suspended scenes. The new scene will be executed.

    Parameters: | scene : Scene It is the scene that will be run.

  `replace`(scene)

    Replaces the running scene with a new one. The running scene is terminated.

    Parameters: | scene : Scene It is the scene that will be run.

  `run`(scene)

    Runs a scene, entering in the Director’s main loop.

    Parameters: | scene : Scene The scene that will be run.

  `scaled_resize_window`(width, height)

    One of two possible methods that are called when the main window is resized.

    This implementation scales the display such that the initial resolution requested by the programmer (the “logical” resolution) is always retained and the content scaled to fit the physical display.

    This implementation also sets up a 3D projection for compatibility with the largest set of Cocos transforms.

    The other implementation is unscaled_resize_window.

    Parameters: | width : Integer New width height : Integer New height

  `set_alpha_blending`(on=True)

    Enables/Disables alpha blending in OpenGL using the GL_ONE_MINUS_SRC_ALPHA algorithm. On by default.

  `set_depth_test`(on=True)

    Enables z test. On by default

  `set_projection`()

    placeholder, will be set to one of set_projection2D or set_projection3D when director.init is called

  `set_projection2D`()

    Sets a 2D projection (ortho) covering all the window

  `set_projection3D`()

    Sets a 3D projection mantaining the aspect ratio of the original window size

  `set_recorder`(framerate, template='frame-%d.png', duration=None)

    Will replace the app clock so that now we can ensure a steady frame rate and save one image per frame

    :Parameters
      framerate: int
        the number of frames per second
      template: str
        the template that will be completed with an in for the name of the files
      duration: float
        the amount of seconds to record, or 0 for infinite
  `set_show_FPS`(value)
  `unscaled_resize_window`(width, height)

    One of two possible methods that are called when the main window is resized.

    This implementation does not scale the display but rather forces the logical resolution to match the physical one.

    This implementation sets up a 2D projection, resulting in the best pixel alignment possible. This is good for text and other detailed 2d graphics rendering.

    The other implementation is scaled_resize_window.

    Parameters: | width : Integer New width height : Integer New height

  `event_types` = ['on_push', 'on_pop', 'on_resize', 'on_cocos_resize']
  `fps_display` = None
  `interpreter_locals` = {'director': <cocos.director.Director object at 0x00000000043A5940>, 'cocos': <module 'cocos' from 'K:\\cocos_pristine\\cocos_2d_new\\cocos\\__init__.py'>}

    a dict with locals for the interactive python interpreter (fill with what you need)

  `show_FPS`

class `DefaultHandler`

  Bases: `object`

  `on_key_press`(symbol, modifiers)