The main module for drawing and user input.

Note: The driver model has completely changed in v0.11.

Drivers make up the bottom layer of the Scenic architectural stack. They draw everything on the screen and originate the raw user input. In general, different drawing targets will need different drivers.

The driver interface provides a great deal of flexibility, but is more advanced than writing scenes. You can write drivers that only provide user input, only draw scripts, or do both. There is no assumption at all as to what the output target or user source is.

Starting Drivers

Drivers are always managed by a ViewPort that hosts them.

The most common way to instantiate a driver is set it up in the config of a ViewPort when it starts up.

config :my_app, :viewport,
  size: {800, 600},
  name: :main_viewport,
  theme: :dark,
  default_scene: MyApp.Scene.MainScene,
  drivers: [
    [
      module: Scenic.Driver.Local,
      name: :local_driver,
      window: [title: "My Application", resizeable: false]
    ],
    [
      module: MyApp.Driver.MyDriver,
      my_param: "abc"
    ],
  ]

In the example above, two drivers are configured to be started when the :main_viewport starts up. Both drivers drivers will be running at the same time and will receive the same messages from the ViewPort.

Drivers can be dynamically started on a ViewPort using Scenic.ViewPort.start_driver/2. They can be dyncamically stopped on a ViewPort using Scenic.ViewPort.stop_driver/2.

Drivers can also define their own configuration options. See the documentation for the driver you are interested in starting to see the available options.

Messages from the ViewPort

The way a ViewPort communicates with it's drivers is by sending them a set of well-known messages. These are picked up by the Driver module and sent to your driver through callbacks.

Handling Updates

The main drawing related task of a Driver is to receive the update_scene/2 callback and then draw the updated scripts to the screen, or whatever output medium the driver supports.

In a very simple example, it would look something like this.

def update_scene( ids, driver ) do
  Enum.each( ids, fn(id) ->
    with {:ok, script} <- ViewPort.get_script_by_id(vp, id) do
      script
      |> Scenic.Script.serialize()
      |> my_render_script(driver)
    end
  end)
  {:ok, driver}
end

The above example is overly simple and just there to get you started. Note that only the ids of the scripts are sent. You still need to fish them out of the ViewPort

User Input

User input events are created whenever a driver has events to share. The request_input/2 callback indicates to you which input events are currently being listened to. This is a guide that you can use or not. You can send any valid input event at any time, the ViewPort will simply ignore those that aren't being listened to.

In this example, there is some source of user input that casts messages to our driver.

def handle_cast( {:my_cursor_press, button, xy}, driver ) do
  send_input(driver, {:cursor_button, {button, 1, [], xy}} )
  { :noreply, driver }
end

No matter what type of input you are sending, it will be checked to make sure it conforms the known input types.

Updated Input Formats

There are several changes to the input formats in version v0.11.

Button indicators are now atoms that conform to standard linux-like buttons. This allows for more buttons on a mouse like device. Do not assume these are the only buttons that can be sent in a :cursor_button message.

Press and Release messages were atoms and are now numbers. This is to support multi-state buttons and joysticks and the like. Turns out that some buttons are pressure sensitive and can have a range of values.

Modifier keys were previously a number and you would have had to dig into the GLFW documentation to see how to interpret it. That was both unintuitive and I wanted to make it more source independent. So now it is a list of atoms. If the atom you are interested is in the list, then it is pressed.

[:ctrl, :shift, :alt, :meta]

Test if a modifier key is pressed using the Enum.member?/2 function.

mods = [:ctrl, :shift]
Enum.member?( mods, :shift )