└── README.md


/README.md:
--------------------------------------------------------------------------------
  1 | # Javascript Guide
  2 | 
  3 | Photopea is a set of libraries and other tools, written in Javascript. This guide shows our style of writing code, 
  4 | and mentions various related web technologies. It can be useful for writing any high-performance Javascript programs.
  5 | 
  6 | We expect, that you already understand programming and at least one programming language.
  7 | It is necessary to know the syntax of Javascript. You can learn it e.g. at [w3schools.com/js](https://www.w3schools.com/js/).
  8 | 
  9 | ## Code style
 10 | We try to avoid syntactic sugar. We always follow these rules when writing code:
 11 | 
 12 | - use `var` instead of combining `var` / `let` / `const`
 13 | - use `"hi"` instead of `'hi'` (quotation marks for strings)
 14 | - use `==` instead of `===` (compare only values with the same data type) 
 15 | - use `null` instead of `undefined`
 16 | - use `obj["prop"]==null` to check, if an object has a specific property
 17 | - omit curly brackets if possible: `if(x) run();`  instead of `if(x) { run(); }`
 18 | 
 19 | ## Static functions
 20 | 
 21 | Many of our code consists only of "static functions". These functions get all necessary data on the input. 
 22 | There is no `this`, `new`, `prototype` in such code. Functions are joined together by being defined as properties of one global object.
 23 | All our public libraries (UPNG.js, UTIF.js, Typr.js ...) have such form.
 24 | 
 25 | ```js
 26 | var Point2D = {};  
 27 | Point2D.length = function(p) {  return Math.sqrt(p.x*p.x + p.y*p.y);  }
 28 | var Point3D = {};  
 29 | Point3D.length = function(p) {  var len = Point2D.length(p);  return Math.sqrt(len*len + p.z*p.z);  }
 30 | ```
 31 | ```js
 32 | var A = {x:1,y:1}, B = {x:1,y:1,z:1};  
 33 | console.log(Point2D.length(A), Point3D.length(B));
 34 | ```
 35 | 
 36 | Such code is easy to rewrite into C (omit the global object `var ABC = {};`, change function names from `ABC.xyz` to `ABC_xyz`). 
 37 | Objects can be `struct`s. They never have methods.
 38 | 
 39 | ## Prototypes
 40 | 
 41 | You should be familiar with prototype-based programming, at least to a degree to understand the following code:
 42 | 
 43 | ```js
 44 | function Point2D(x, y) {
 45 |   this.x = x;
 46 |   this.y = y;
 47 | }
 48 | Point2D.prototype.length = function() {
 49 |   return Math.sqrt(this.x*this.x + this.y*this.y);
 50 | }
 51 | ```
 52 | 
 53 | ```js
 54 | function Point3D(x, y, z) {
 55 |   Point2D.call(this, x, y);
 56 |   this.z = z;
 57 | }
 58 | Point3D.prototype = new Point2D();
 59 | Point3D.prototype.length = function() {
 60 |   var len = Point2D.prototype.length.call(this);
 61 |   return Math.sqrt(len*len + this.z*this.z);
 62 | }
 63 | ```
 64 | ```js
 65 | var A = new Point2D(1,1), B = new Point3D(1,1,1);  
 66 | console.log(A.length(), B.length());
 67 | ```
 68 | 
 69 | ## Anonymous Functions
 70 | 
 71 | Let's say we want to have an array A of all primes between 0 and 1000. We can use a following code.
 72 | 
 73 | ```js
 74 | var A = [];
 75 | for(var i=2; i<1000; i++) {
 76 |     var prime=true;  for(var j=2; j<i-1; j++) if((i%j)==0) prime=false;
 77 |     if(prime) A.push(i);
 78 | }
 79 | ```
 80 | When the code finishes, the the environment is "polluted" with variables A, i, j, prime. We can improve it.
 81 | 
 82 | ```js
 83 | var getPrimes = function() {
 84 |   var pr = [];
 85 |   for(var i=2; i<1000; i++) {
 86 |       var prime=true;  for(var j=2; j<i-1; j++) if((i%j)==0) prime=false;
 87 |       if(prime) pr.push(i);
 88 |   }
 89 |   return pr;
 90 | }
 91 | var A = getPrimes();
 92 | ```
 93 | But still, the environment is polluted with variables A and getPrimes. It can be done better:
 94 | 
 95 | ```js
 96 | var A = function() {
 97 |   var pr = [];
 98 |   for(var i=2; i<1000; i++) {
 99 |       var prime=true;  for(var j=2; j<i-1; j++) if((i%j)==0) prime=false;
100 |       if(prime) pr.push(i);
101 |   }
102 |   return pr;
103 | } ();
104 | ```
105 | The function is called right after being defined. It does not have a name, so it can not be called from any other part of code. Only a variable A (array of primes) is defined in the environment after the execution.
106 | 
107 | ## Typed Arrays
108 | 
109 | You should be familiar with [Typed Arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays), 
110 | as they are heavily used in Photopea to store large data.
111 | 
112 | 
113 | ## Garbage-sensitive programming
114 | 
115 | In our programs, we may have objects with the similar structure (e.g. 2D points, matrices, buttons, windows ...).
116 | 
117 | When there are dozens or hundreds of such objects, we can represent them as JS objects / arrays:
118 | 
119 | ```js
120 | var points = [];  for(var i=0; i<30; i++) points.push( {x:i, y:3+2*i} );
121 | function print(k) {  console.log(points[k].x, points[k].y);  }
122 | ```
123 | 
124 | ```js
125 | var points = [];  for(var i=0; i<30; i++) points.push( [i, 3+2*i] );
126 | function print(k) {  console.log(points[k][0], points[k][1]);  }
127 | ```
128 | 
129 | When there are thousands or millions of such objects, we represent them in a "flat" array (typed array)
130 | 
131 | ```js
132 | var points = [];  for(var i=0; i<30; i++) points.push( i, 3+2*i );
133 | function print(k) {  console.log(points[2*k], points[2*k+1]);  }
134 | ```
135 | ```js
136 | var points = new Float32Array(60);  for(var i=0; i<30; i++) {  points[2*i]=i;  points[2*i+1]=3+2*i;  }
137 | function print(k) {  console.log(points[2*k], points[2*k+1]);  }
138 | ```
139 | 
140 | The flat representation needs less memory and is easier to collect by GC (as there is only one JS object).
141 | Such flat list of objects is processed faster (as there are usually less jumps in memory).
142 | 
143 | ## Local HTTP server
144 | 
145 | To test your code locally, and let it load local files over HTTP protocol, you need a local HTTP server. Using it is easier than it sounds. Here is how to do it on Windows.
146 | 
147 | Download NGIX from `http://nginx.org/en/download.html` . Unzip it, open the `conf/nginx.conf` and replace its content with following:
148 | 
149 | ```
150 | worker_processes  1;
151 | events {
152 |     worker_connections  1024;
153 | }
154 | http {
155 |     include       mime.types;
156 |     default_type  application/octet-stream;
157 |     sendfile        on;
158 |     keepalive_timeout  65;
159 |     server {
160 |         listen       8887;
161 |         server_name  http://127.0.0.1;
162 |         location / {
163 |             root   C:/Desktop/.....;
164 |         }
165 |     }
166 | }
167 | ```
168 | - replace the `C:/Desktop/.....` with the directory, that should be accessible from a browser
169 | - double-click the `nginx.exe` to start it. It will run in a background, using 1 MB of RAM 
170 | - you can view `C:/Desktop/XYZ/file.html` by navigating to `http://127.0.0.1:8887/file.html` in any browser
171 | 
172 | 
173 | 


--------------------------------------------------------------------------------