├── MIT-LICENSE.txt ├── gamera.lua └── README.md /MIT-LICENSE.txt: -------------------------------------------------------------------------------- 1 | Copyright (c) 2011 Enrique García Cota 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a 4 | copy of this software and associated documentation files (the 5 | "Software"), to deal in the Software without restriction, including 6 | without limitation the rights to use, copy, modify, merge, publish, 7 | distribute, sublicense, and/or sell copies of the Software, and to 8 | permit persons to whom the Software is furnished to do so, subject to 9 | the following conditions: 10 | 11 | The above copyright notice and this permission notice shall be included 12 | in all copies or substantial portions of the Software. 13 | 14 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 15 | OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 16 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 17 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 18 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 19 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 20 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /gamera.lua: -------------------------------------------------------------------------------- 1 | -- gamera.lua v1.0.1 2 | 3 | -- Copyright (c) 2018 Enrique García Cota 4 | -- Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 5 | -- The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 6 | -- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 7 | -- Based on YaciCode, from Julien Patte and LuaObject, from Sebastien Rocca-Serra 8 | 9 | local gamera = {} 10 | 11 | -- Private attributes and methods 12 | 13 | local gameraMt = {__index = gamera} 14 | local abs, min, max = math.abs, math.min, math.max 15 | 16 | local function clamp(x, minX, maxX) 17 | return x < minX and minX or (x>maxX and maxX or x) 18 | end 19 | 20 | local function checkNumber(value, name) 21 | if type(value) ~= 'number' then 22 | error(name .. " must be a number (was: " .. tostring(value) .. ")") 23 | end 24 | end 25 | 26 | local function checkPositiveNumber(value, name) 27 | if type(value) ~= 'number' or value <=0 then 28 | error(name .. " must be a positive number (was: " .. tostring(value) ..")") 29 | end 30 | end 31 | 32 | local function checkAABB(l,t,w,h) 33 | checkNumber(l, "l") 34 | checkNumber(t, "t") 35 | checkPositiveNumber(w, "w") 36 | checkPositiveNumber(h, "h") 37 | end 38 | 39 | local function getVisibleArea(self, scale) 40 | scale = scale or self.scale 41 | local sin, cos = abs(self.sin), abs(self.cos) 42 | local w,h = self.w / scale, self.h / scale 43 | w,h = cos*w + sin*h, sin*w + cos*h 44 | return min(w,self.ww), min(h, self.wh) 45 | end 46 | 47 | local function cornerTransform(self, x,y) 48 | local scale, sin, cos = self.scale, self.sin, self.cos 49 | x,y = x - self.x, y - self.y 50 | x,y = -cos*x + sin*y, -sin*x - cos*y 51 | return self.x - (x/scale + self.l), self.y - (y/scale + self.t) 52 | end 53 | 54 | local function adjustPosition(self) 55 | local wl,wt,ww,wh = self.wl, self.wt, self.ww, self.wh 56 | local w,h = getVisibleArea(self) 57 | local w2,h2 = w*0.5, h*0.5 58 | 59 | local left, right = wl + w2, wl + ww - w2 60 | local top, bottom = wt + h2, wt + wh - h2 61 | 62 | self.x, self.y = clamp(self.x, left, right), clamp(self.y, top, bottom) 63 | end 64 | 65 | local function adjustScale(self) 66 | local w,h,ww,wh = self.w, self.h, self.ww, self.wh 67 | local rw,rh = getVisibleArea(self, 1) -- rotated frame: area around the window, rotated without scaling 68 | local sx,sy = rw/ww, rh/wh -- vert/horiz scale: minimun scales that the window needs to occupy the world 69 | local rscale = max(sx,sy) 70 | 71 | self.scale = max(self.scale, rscale) 72 | end 73 | 74 | -- Public interface 75 | 76 | function gamera.new(l,t,w,h) 77 | 78 | local sw,sh = love.graphics.getWidth(), love.graphics.getHeight() 79 | 80 | local cam = setmetatable({ 81 | x=0, y=0, 82 | scale=1, 83 | angle=0, sin=math.sin(0), cos=math.cos(0), 84 | l=0, t=0, w=sw, h=sh, w2=sw*0.5, h2=sh*0.5 85 | }, gameraMt) 86 | 87 | cam:setWorld(l,t,w,h) 88 | 89 | return cam 90 | end 91 | 92 | function gamera:setWorld(l,t,w,h) 93 | checkAABB(l,t,w,h) 94 | 95 | self.wl, self.wt, self.ww, self.wh = l,t,w,h 96 | 97 | adjustPosition(self) 98 | end 99 | 100 | function gamera:setWindow(l,t,w,h) 101 | checkAABB(l,t,w,h) 102 | 103 | self.l, self.t, self.w, self.h, self.w2, self.h2 = l,t,w,h, w*0.5, h*0.5 104 | 105 | adjustPosition(self) 106 | end 107 | 108 | function gamera:setPosition(x,y) 109 | checkNumber(x, "x") 110 | checkNumber(y, "y") 111 | 112 | self.x, self.y = x,y 113 | 114 | adjustPosition(self) 115 | end 116 | 117 | function gamera:setScale(scale) 118 | checkNumber(scale, "scale") 119 | 120 | self.scale = scale 121 | 122 | adjustScale(self) 123 | adjustPosition(self) 124 | end 125 | 126 | function gamera:setAngle(angle) 127 | checkNumber(angle, "angle") 128 | 129 | self.angle = angle 130 | self.cos, self.sin = math.cos(angle), math.sin(angle) 131 | 132 | adjustScale(self) 133 | adjustPosition(self) 134 | end 135 | 136 | function gamera:getWorld() 137 | return self.wl, self.wt, self.ww, self.wh 138 | end 139 | 140 | function gamera:getWindow() 141 | return self.l, self.t, self.w, self.h 142 | end 143 | 144 | function gamera:getPosition() 145 | return self.x, self.y 146 | end 147 | 148 | function gamera:getScale() 149 | return self.scale 150 | end 151 | 152 | function gamera:getAngle() 153 | return self.angle 154 | end 155 | 156 | function gamera:getVisible() 157 | local w,h = getVisibleArea(self) 158 | return self.x - w*0.5, self.y - h*0.5, w, h 159 | end 160 | 161 | function gamera:getVisibleCorners() 162 | local x,y,w2,h2 = self.x, self.y, self.w2, self.h2 163 | 164 | local x1,y1 = cornerTransform(self, x-w2,y-h2) 165 | local x2,y2 = cornerTransform(self, x+w2,y-h2) 166 | local x3,y3 = cornerTransform(self, x+w2,y+h2) 167 | local x4,y4 = cornerTransform(self, x-w2,y+h2) 168 | 169 | return x1,y1,x2,y2,x3,y3,x4,y4 170 | end 171 | 172 | function gamera:draw(f) 173 | local sx, sy, sw, sh = love.graphics.getScissor() 174 | love.graphics.setScissor(self:getWindow()) 175 | 176 | love.graphics.push() 177 | local scale = self.scale 178 | love.graphics.scale(scale) 179 | 180 | love.graphics.translate((self.w2 + self.l) / scale, (self.h2+self.t) / scale) 181 | love.graphics.rotate(-self.angle) 182 | love.graphics.translate(-self.x, -self.y) 183 | 184 | f(self:getVisible()) 185 | 186 | love.graphics.pop() 187 | 188 | love.graphics.setScissor(sx, sy, sw, sh) 189 | end 190 | 191 | function gamera:toWorld(x,y) 192 | local scale, sin, cos = self.scale, self.sin, self.cos 193 | x,y = (x - self.w2 - self.l) / scale, (y - self.h2 - self.t) / scale 194 | x,y = cos*x - sin*y, sin*x + cos*y 195 | return x + self.x, y + self.y 196 | end 197 | 198 | function gamera:toScreen(x,y) 199 | local scale, sin, cos = self.scale, self.sin, self.cos 200 | x,y = x - self.x, y - self.y 201 | x,y = cos*x + sin*y, -sin*x + cos*y 202 | return scale * x + self.w2 + self.l, scale * y + self.h2 + self.t 203 | end 204 | 205 | return gamera 206 | 207 | 208 | 209 | 210 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | gamera.lua 2 | ========== 3 | 4 | A camera for [LÖVE](http://love2d.org). 5 | 6 | Initial setup 7 | ------------- 8 | 9 | The first thing one needs to do to use gamera is to create it. You do so with `gamera.new`. This function requires 4 numbers (left, top, width and height) defining the "world boundaries" for the camera. 10 | ``` lua 11 | local cam = gamera.new(0,0,2000,2000) 12 | ``` 13 | The left and top parameters are usually 0,0, but they can be anything, even negative numbers (see below). 14 | 15 | You can update the world definition later on with `setWorld`: 16 | ``` lua 17 | cam:setWorld(0,0,2000,2000) 18 | ``` 19 | By default gamera will use the whole screen to display graphics. You can restrict the amount of screen used with `setWindow`: 20 | ``` lua 21 | cam:setWindow(0,0,800,600) 22 | ``` 23 | Moving the camera around 24 | ------------------------ 25 | 26 | You can move the camera around by using `setPosition`: 27 | ``` lua 28 | cam:setPosition(100, 200) 29 | ``` 30 | `setPosition` takes into account the current window boundaries and world boundaries, and will keep the view inside the world. This means that if you try to look at something very close to the left border of the world, for example, the camera will not "scroll" to show empty space. 31 | 32 | You can also zoom in and zoom out. This is done using the `setScale` method. It's got a single parameter, which is used for increasing and decreasing the height and width. The default scale is 1.0. 33 | ``` lua 34 | cam:setScale(2.0) -- make everything twice as bigger. By default, scale is 1 (no change) 35 | ``` 36 | Take notice that gamera limits the amount of zoom out you can make; you can not "zoom out" to see the world edges. If you want to do this, make the world bigger first. For example, to give a 100-pixels border to a world defined as `0,0,2000,`, you can define it like `-100,100,2100,2100` instead. 37 | 38 | Finally, you can modify the angle with `setAngle`: 39 | ``` lua 40 | cam:setAngle(newAngle) -- newAngle is in radians, by default the angle is 0 41 | ``` 42 | `setAngle` will change *both* the scale and position of the camera to force you not to see the world borders. If you don't want this to happen, expand the world borders as mentioned above. 43 | 44 | Drawing 45 | ------- 46 | 47 | The camera has one method called "draw". It takes one function as a parameter. Here's one example: 48 | ``` lua 49 | local function drawCameraStuff(l,t,w,h) 50 | -- draw stuff that will be affected by the camera, for example: 51 | drawBackground(l,t,w,h) 52 | drawTiles(l,t,w,h) 53 | drawEntities(l,t,w,h) 54 | end 55 | 56 | ... 57 | 58 | -- pass your custom function to cam:draw when you want to draw stuff 59 | cam:draw(drawCameraStuff) 60 | ``` 61 | 62 | Alternatively, you could create a custom anonymous function and pass it to `cam:draw`, but in some extreme cases this could have a non-negligible performance impact. 63 | 64 | ``` 65 | cam:draw(function(l,t,w,h) 66 | -- draw camera stuff here 67 | end) 68 | ``` 69 | 70 | Anything drawn inside the custom function you pass to `cam:draw` be modified by the camera (scaled, rotated, translated and cut) so that it appears as it should in the screen window. 71 | 72 | Notice that the function takes 4 optional parameters. These parameters represent the area that the camera "sees" (same as calling `cam:getVisible()`). They can be used to optimize the drawing, and not draw anything outside of those borders. Those borders are always axis-aligned. This means that when the camera is rotated, the area might include elements that are not strictly visible. 73 | 74 | 75 | Querying the camera 76 | ------------------- 77 | 78 | * `cam:getWorld()` returns the l,t,w,h of the world 79 | * `cam:getWindow()` returns the l,t,w,h of the screen window 80 | * `cam:getVisible()` returns the l,t,w,h of what is currently visible in the world, taking into account rotation, scale and translation. It coincides with the parameters of the callback function in `gamera.draw`. It can contain more than what is necessary due to rotation. 81 | * `cam:getVisibleCorners()` returns the corners of the rotated rectangle that represent the exact region being seen by the camera, in the form `x1,y1,x2,y2,x3,y3,x4,y4` 82 | 83 | * `cam:getPosition()` returns the coordinates the camera is currently "looking at", after it has been corrected so that the world boundaries are not visible, if possible. 84 | * `cam:getScale()` returns the current scaleX and scaleY parameters 85 | * `cam:getAngle()` returns the current rotation angle, in radians 86 | 87 | Coordinate transformations 88 | -------------------------- 89 | 90 | * `cam:toWorld(x,y)` transforms screen coordinates into world coordinates, taking into account the window, scale, rotation and translation. Useful for mouse interaction, for example. 91 | * `cam:toScreen(x,y)` transforms given a coordinate in the world, return the real coords it has on the screen. Useul to represent icons in minimaps, for example. 92 | 93 | FAQ 94 | === 95 | 96 | > Everything looks kindof "blurry" when I do zooms/rotations with this library. How do I prevent it? 97 | 98 | LÖVE uses a default [filter mode](https://love2d.org/wiki/FilterMode) which makes images "blurry" when you make almost any transformation to them. To deactivate this behavior globally, you can add this at the beginning of your game, before you load anything (for example at the beginning of `love.load`): 99 | 100 | ``` lua 101 | love.graphics.setDefaultFilter( 'nearest', 'nearest' ) 102 | ``` 103 | 104 | You can also set the filter of each image you load individually: 105 | 106 | ``` lua 107 | local img = love.graphics.newImage('imgs/player.png') 108 | img:setFilter('nearest', 'nearest') 109 | ``` 110 | 111 | > I see "seams" around my tiles when I use this library. Why? 112 | 113 | It is due to a combination of factors: how OpenGL textures work, how floating point numbers work and how LÖVE stores texture information in memory. 114 | 115 | The end result is that sometimes, when drawing an image, "parts of the area around it" are also drawn. So if you draw a Quad of "earth", and immediately above it in your image you have a "bright lava" tile, when you draw the earth tile sometimes "a bit of the lava" is drawn near the top. If you are using images instead of quads, you can get seams too (either black or from other colors, depending on how the image is stored in memory). 116 | 117 | To prevent this: 118 | 119 | * Always use quads for tiles, never images. 120 | * Add a 2-pixel border to each of your quads (So for a 32x32 quad, you use 36x36 space, with the 32x32 quad in the center and a 2-pixel border) 121 | * Fill up the borders with the colors of the 32x32 quad. For example, if the earth quad is all brown on its left side, color the left border brown. If on its upper side is gray in the center and brown on the sides, color the upper border gray in the center and brown on the sides. 122 | * The quads will still be 32x32 - they will just have some border in the image now. 123 | * The "seams" will still appear, but now they will show the "colored borders" of the quads, so they will not be noticeable. 124 | * Calculating the coordinates of the quads is a bit more complex than before. You can use [anim8](https://github.com/kikito/anim8)'s "Grids" to simplify getting them: 125 | 126 | ``` lua 127 | local anim8 = require 'anim8' 128 | 129 | ... 130 | 131 | local tiles = love.graphics.newImage('tiles.png') 132 | local w,h = tiles:getDimensions() 133 | 134 | local g = anim8.newGrid(32, 32, w, h, 0, 0, 2) -- tileWidth, tileHeight, imageW, imageH, left, top, border 135 | 136 | local earth = g(1,1)[1] -- Get the first column, first row 32x32 quad, including border 137 | local water = g(2,1)[1] -- Get the second column, first row quad 138 | ``` 139 | 140 | You can combine this with the previous FAQ and use a "nearest" filter instead of a linear one. 141 | 142 | > The camera is "clamping". I don't want it to clamp 143 | 144 | Yes, by default `gamera` cameras make sure that they always "stay in the world". They never "show black borders" around the scene. 145 | 146 | There is no way to deactivate this behaviour. However, you can "mimic" it very well. It's actually very simple: give the camera a 147 | bigger world. 148 | 149 | For example, if instead of doing this: 150 | 151 | ``` lua 152 | local cam = gamera.new(0,0,2000,2000) 153 | ``` 154 | 155 | You do this: 156 | 157 | ``` lua 158 | local cam = gamera.new(-200,-200,2200,2200) 159 | ``` 160 | 161 | You will give the world a 200 pixel "black border" which will be visible when the camera zooms out or moves to the left or right. 162 | 163 | If you want to display the borders only sometimes, you can use `setWorld` to activate/deactivate the zoom: 164 | 165 | ``` lua 166 | local cam = gamera.new(0,0,2000,2000) 167 | 168 | ... -- the camera "clamps" when drawing 169 | 170 | cam:setWorld(-200,-200,2200,2200) 171 | 172 | ... -- Now the camera has a 200px border 173 | 174 | cam:setWorld(0,0,2000,2000) 175 | 176 | ... -- now it clamps again 177 | 178 | ``` 179 | 180 | Installation 181 | ============ 182 | 183 | Just copy the gamera.lua file wherever you want it. Then require it where you need it: 184 | ``` lua 185 | local gamera = require 'gamera' 186 | ``` 187 | Please make sure that you read the license, too (for your convenience it's included at the beginning of the gamera.lua file). 188 | 189 | --------------------------------------------------------------------------------