# Getting started

This document is an introduction to making live visuals using Hydra. It covers the basics of writing code in the browser to generate and mix live video sources. No coding or video experience is necessary !

If you just want to start in 60 seconds you can also check:
* [Getting started short version](https://hackmd.io/@r08UjGF3QMCfvNmdjuY7iQ/rJCpsbNNc)

This tutorial is meant to be used from within the [hydra web editor](https://hydra.ojack.xyz/). It is also interactive -- you can directly modify the code in each code block to see how it affects the visuals.

### Get to know the browser editor
To get started, open the the [hydra web editor](https://hydra.ojack.xyz/) in a separate window. Close the top window by clicking the [x] in the top right.


You will see some colorful visuals in the background with text on top in the top left of the screen. The text is code that generates the visuals behind it.

At the right up corner you will find a toolbar with these buttons: 
1. **Play button.** You can use it to run the code.
2. Upload your sketch to Hydra's gallery **(not working for the moment)**
3. **Clear all** and start from scratch.
4. **Random sketch examples**. It shows random sketch examples. Always it is a good way to learn Hydra by studying someone elses code.
5. Make random change, **dices** modify values automatically. Try it with some of the sketches examples.
6. **Help menu** with useful links.

## First line of code

Use the ***clear all***  button to erase the previous sketch.

 ###### _clear all_ button Then, type or paste the following in the editor:

osc().out()

Press the ***run*** button to run this code and update the visuals on the screen. You should see some scrolling stripes appear in the background.

###### run button

osc().out()


This creates a visual oscillator. Try modifying the parameters of the oscillator by putting a number inside the parentheses of `osc()`, for example ```osc(10).out()```.

Re-run the code by pressing the ***run*** button again, and seeing the visuals update. Try adding other values to control the oscillator's `frequency`, `sync`, and `color offset`.

osc(5, -0.126, 0.514).out()

*Trick: you can also use the keyboard shortcut **‘ctrl + shift + enter’** to have the same effect as the run button.*

## Adding transformations
We can add another transformation to the oscillator from above, by adding the function `rotate()` after the oscillator:

osc(5,-0.126,0.514).rotate().out()

As you can see, you have first an input source `osc()` and things that come after (`rotate()` and `out()`) are connected with a dot ‘.’
In this sense, Hydra is inspired by modular synthesis.
Analogue modular synthezisers used different kind of input electric wave signs, patching cables to different filters this signs were modified in order to create different visuals.
Instead of connecting cables you connect different kinds of javascript functions.
###### source [Sandin Image Processor](https://en.wikipedia.org/wiki/Sandin_Image_Processor)
###### more about [modular synthesizers](https://en.wikipedia.org/wiki/Modular_synthesizer)

You can continue adding transformations to this chain of functions. For example:

osc(5,-0.126,0.514).rotate(0, 0.2).kaleid().out()

Repeat:

osc(5,-0.126,0.514).rotate(0, 0.2).kaleid().repeat().out()

For more available sources and transformations, see the [interactive function reference](https://hydra.ojack.xyz/api).
The logic is to start with a ***source*** (such as `osc()`, `shape()`, or `noise()`), and then add transformations to ***geometry*** and ***color*** (such as `.rotate()`, `.kaleid()`, `.pixelate()` ), and in the end always connect the chain of transformations to the output screen `.out()` .

noise(4).color(-2, 1).colorama().out()

shape(3).repeat(3, 2).scrollX(0, 0.1).out()

## What is an error?
Sometimes, you will try to run a line of code, and nothing will happen. If you have an error you’ll notice text in red at the left-bottom on your screen. Something like ‘Unexpected token ‘.’ (in red) will appear. This doesn’t affect your code, but you won’t be able to continue coding until you fix the error. Usually it is a typing error or something related to the syntax.

## What is a comment?

// Hello I’m a comment line. I’m a text that won’t change your code. You can write notations, your name or even a poem here.

## Save your sketch on the internet

When you evaluate the entire code with the ***run button*** or with `shift + ctrl + enter`, Hydra automatically generates a URL that contains the last changes of your sketch. You can copy and paste the url from the URL bar to save it or share it with other people. You can also use the browser `back` and `forward` arrows to navigate to earlier versions of your sketch.

## Using the webcam
In addition to using sources from within hydra (such as `osc()` and `shape()`), you can use hydra to process external video sources such as a webcam. To initialize the webcam, run the following code:

s0.initCam()

This activates the webcam source inside a variable called `s0`, and you should see the light on your webcam light up. However, you will still not see the webcam image on the screen. In order to use the camera within a hydra sketch, you need to use it within the `src()` function.

s0.initCam() //initialize webcam as external source 's0'
src(s0).out() // use external source 's0' inside Hydra

Similar to adding transformations above, you can add transformations of color and geometry to the camera output, by adding functions to the chain:

s0.initCam()
src(s0).color(-1, 1).out()

s0.initCam()
src(s0).color(-1, 1).kaleid().out()

If you have multiple webcams, you can access separate cameras by adding a number inside `initCam`, for example `s0.initCam(1)` or `s0.initCam(2)`.

## Multiple outputs

By default, hydra contains four separate virtual outputs that can each render different visuals, and can be mixed with each other to create more complex visuals. The variables `o0`, `o1`, `o2`, and `o3` correspond to the different outputs.

To see all four of the outputs at once, use the `render()` function. This will divide the screen into four, showing each output in a different section of the screen.


Using a different variable inside the `.out()` function renders the chain to a different output. For example, `.out(o1)` will render a function chain to graphics buffer `o1`.

gradient(1).out(o0) // render a gradient to output o0
osc().out(o1) // render voronoi to output o1
voronoi().out(o2) // render voronoi to output o2
noise().out(o3)  // render noise to output o3

render()  // show all outputs

By default, only output `o0` is rendered to the screen, while the `render()` command divides the screen in four. Show a specific output on the screen by adding it inside of `render()`, for example `render(o2)` to show buffer `o2`.

gradient(1).out(o0) // render a gradient to output o0
osc().out(o1) // render voronoi to output o1
voronoi().out(o2) // render voronoi to output o2
noise().out(o3)  // render noise to output o3

render(o2)  // show only output o2

*Trick: try to create different sketches and switch them in your live performance or even combine them.*

gradient(1).out(o0)
osc().out(o1)
render(o0) //switch render output
// render(o1) 

## Blending multiple visual sources together
You can use ***blend*** functions to combine multiple visual sources. `.blend()` combines the colors from two sources to create a third source.

s0.initCam()

src(s0).out(o0) // render the webcam to output o0

osc(10).out(o1) // render an oscillator to output o1

src(o0).blend(o1).out(o2) // start with o0, mix it with o1, and send it out to o2

render() // render all four outputs at once

Try adding transformations to the above sources (such as `osc(10).rotate(0, 0.1).out(o1)`) to see how it affects the combined image. You can also specify the amount of blending by adding a separate parameter to `.blend()`, for example `.blend(o1, 0.9)`.

There are multiple [blend modes](https://en.wikipedia.org/wiki/Blend_modes) in hydra, similar to blend modes you might find in a graphics program such as photoshop or gimp. See [the function reference](https://hydra.ojack.xyz/api/) for more possibilities.

s0.initCam()

src(s0).out(o0) // render the webcam to output o0

osc(10).out(o1) // render an oscillator to output o1

src(o0).diff(o1).out(o2) // combine different signals by color difference (dark portions become inverted).

render() // render all four outputs at once

## Modulation
While ***blend*** functions combine the colors from two visual sources, ***modulate*** functions use the colors from one source to affect the ***geometry*** of the second source. This creates a sort of warping or distorting effect. An analogy in the real world would be looking through a texture glass window.
`modulate()` does not change color or luminosity but distorts one visual source using another visual source.

Using the same sources from above, we can use an oscillator to modulate or warp the camera image:

s0.initCam()

src(s0).out(o0) // render the webcam to output o0
osc(10).out(o1) // render an oscillator to output o1

src(o0).modulate(o1).out(o2) // use source o1 to distort source o0, lighter areas are distorted more

render() // render all four outputs at once

You can add a second parameter to the `modulate()` function to control the amount of warping: `modulate(o1, 0.9)`. In this case, the red and green channels of the oscillator are being converted to x and y displacement of the camera image.

All ***geometry*** transformations have corresponding ***modulate*** functions that allow you to use one source to warp another source. For example, `.modulateRotate()` is similar to `.rotate()`, but it allows you to apply different amounts of rotation to different parts of the visual source. See [the function reference](https://hydra.ojack.xyz/api/) for more examples.

s0.initCam()

src(s0).out(o0) // render the webcam to output o0
osc(10).out(o1) // render an oscillator to output o1

src(o0).modulateRotate(o1, 2).out(o2) // 

render() // render all four outputs at once

## More blending and modulating

In addition to using multiple outputs to combine visuals, you can also combine multiple sources within the same function chain, without rendering them to separate outputs.

osc(10, 0.1, 1.2).blend(noise(3)).out(o0)

render(o0) // render output o0

This allows you to use many sources, blend modes, and modulation, all from within the same chain of functions.

osc(10, 0.1, 1.2).blend(noise(3)).diff(shape(4, 0.6).rotate(0, 0.1)).out()

*Trick: use `ctrl + shift + f` from the web editor to auto-format your code*

#### Modulating with the camera

s0.initCam() //loads a camera

shape().modulate(src(s0)).out() //shape modulated by a camera

s0.initCam() //loads a camera

src(s0).modulate(shape()).out() //camera modulated by a shape

noise().out(o1)
shape().out(o3)

src(o1).add(src(o3)).out(o2) //additive light. Color only gets brighter

render() 

osc(10).out(o0)

shape().out(o1)

src(o0).diff(o1).out(o2) // combines different signals by color difference (color negative/inverted/opposite).  

render()

osc().mult(src(o1)).out() // multiplies the sources together, 
shape(5).out(o1)

We have now covered all of the basic types of functions within hydra: ***source***, ***geometry***, ***color***, ***blending***, and ***modulation***! See what you can come up with by mixing these together.

#### Have fun!

# Additional Topics

## Videos, Images, and Screensharing

In addition to the webcam, you can also use videos, images, screencaptures and livestreams, as well as canvas sources such as from P5.js and THREE.js. Similar to the webcam, all external sources must be initialized before they can be used within a sketch. This doesn’t mean that you’ll see the effect instantly on your sketch. You need to call the source as you would do it with any input signal in the code. There are 4 input channels that can be used to introduce an external source: s0, s1, s2, s3.

### Images

s0.initImage("https://upload.wikimedia.org/wikipedia/commons/2/25/Hydra-Foto.jpg")
src(s0).out()

### Videos

s0.initVideo("https://media.giphy.com/media/AS9LIFttYzkc0/giphy.mp4")
src(s0).out()

### Screencapture

`initScreen()` function is an external source that can be used in Hydra. Screen captures can be anything you choose to share, it can be a window tab from the browser, anything from your desktop, sticky notes, drawing softwares, video call meetings, or even Hydra in itself (which creates interesting feedback loops to play with).

s0.initScreen() //loads whatever you want to share as a source. Once is loaded is better to comment this line, in order not to run this everytime.

src(s0).kaleid(3).out() //load the source as a signal to play with in Hydra code

### Combining multiple external sources

s0.initScreen()
s1.initCam()

src(s0).modulate(s1).out()

## Sequencing and Interactivity
### Arrays

Arrays in Hydra are a sequenced collection of values. You can use this to change several parameters in time just like a step sequencer.

osc(10,0.1,[10,0,2,0.5]).out()

shape([3,4,200,2]).out()

### Passing functions as variables
Any parameter in hydra that is a number can be defined as a function rather than a static variable. For example,

osc(function(){return 100 * Math.sin(time * 0.1)}).out()

modifies the oscillator frequency as a function of time. (Time is a global variable that represents the milliseconds that have passed since loading the page). This can be written more concisely using es6 syntax:

osc(() => (100 * Math.sin(time * 0.1))).out()

### Audio Reactivity

Make audio reactive visuals using. The audio signal works as an input parameter, you can multiply this value in order to change the amount of changes.

osc(20,0.1, ()=>a.ff[0]*10).out()

## Video Feedback
Output can be used as input source too. This process generates video feedback. Depending on which blend mode and the amount of values used, results can be very different and chaotic.

osc().modulate(src(o0)).out()

src(o0).scrollY(-0.001)
  .add(noise(30),0.001).out()

## live coding: evaluate separate lines or blocks of code

Press ‘ctrl+enter’ to run a line of code.  
Press ‘shift+ctrl+enter’ to evaluate the entire code.  
Press ‘alt+enter’ to evaluate a block of code.  
Tip: You can switch between different lines of code for a live coding performance.

osc().out() //run this first

noise().mult(osc(10,0.1,10)).out() //now try this one

## atom-hydra
Hydra can be used without internet connection (or with it too) with Atom, this is a code editor. For using Hydra in this way, you need to install Atom and node.js in your computer, then search for the Hydra package inside Atom. This is also useful to run videos locally.



## p5.js
p5js library can be used in Hydra as an [external source]. Once p5js code is loaded into Hydra it can be used and combined with Hydra as a pattern or texture for example.

p5 = new P5() // loads p5js library. Must be loaded just once, after running this line of code, it is better to comment it.

//loads p5’s draw function
p5.draw =()=>{
p5.ellipse(p5.windowWidth/2, p5.windowHeight/2,100)
}
p5.hide(); //hide p5 canvas, to use it just as texture in Hydra

s0.init({src:p5.canvas}) //load p5js as input source

src(s0).mult(osc()).out() //p5js source in Hydra as texture

## loadScript()
The await `loadScript()`` function lets you load other packaged javascript libraries within the hydra editor. Any javascript code can run in the hydra editor.
## Custom glsl functions 
Custom glsl functions can be used as custom functions
> [name=Flor de Fuego is okay to say function?]

functionshttps://hydra-book.glitch.me/#/glsl 

## Hydra in a webpage
Hydra can be used inside a HTML site. Hydra’s functions could be modified by buttons, sliders, etc. [Here](https://hydra-webpage.glitch.me/) an example of how it can be used.


--- 


# Glossary:
https://hackmd.io/RCr03ns1RXGa8GBn7BV8xQ



---


4. In-depth guides (How-to)

getting started (naoto)
- how to evaluate line
- sources (solid, gradient, osc, ...)
- evaluate different lines to live code
- color() to change color
- blending
- transform
- load images
- load webcam
additional topics
- modulate
- feedback
- arrays, functions
- sound (audio reactive)
- p5