feat: add kind parameter for beginShape function (supporting LINES, POINTS, TRIANGLE_FAN, TRIANGLE_STRIP, and TRIANGLES)

[georgeibrahim1]

I want to know your feedback @lee2sman

Examples :

require("L5")

function setup() 
  size(400, 400)
  windowTitle("beginShape(LINES) example")
  
  fill(0)
  beginShape(LINES)
  vertex(30, 20);
  vertex(85, 20);
  vertex(85, 75);
  vertex(30, 75);
  endShape()
  describe("custom shape with beginShape(LINES) function, vertices and endShape()")
end

require("L5")

function setup() 
  size(400, 400)
  windowTitle("beginShape(POINTS) example")
  
  fill(0)
  beginShape(POINTS)
  for i=0,10 do
    vertex(random(width),random(height))
  end
  endShape()
  describe("custom shape with beginShape(POINTS) function, vertices and endShape()")
end

Note : love.graphics.points() draws small squares as I mentioned in #9

require("L5")

function setup() 
  size(400, 400)
  windowTitle("beginShape(TRIANGLE_FAN) example")

  fill(150, 200, 255)
  stroke(51)
  strokeWeight(5)

  beginShape(TRIANGLE_FAN)
  vertex(200, 200)  -- center
  vertex(200, 50)   -- top
  vertex(320, 110)
  vertex(370, 250)
  vertex(280, 370)
  vertex(120, 370)
  vertex(30,  250)
  vertex(80,  110)
  vertex(200, 50)
  endShape()

  describe("octagon drawn with beginShape(TRIANGLE_FAN) from a center point, with stroke")
end

for TRIANGLE_FAN,I didn't want to use the implmented code for the other shapes (as beginShape() uses fan by default) to make the code readable

require("L5")

function setup()
  size(400, 400)
  windowTitle("beginShape(TRIANGLE_STRIP) example")

  fill(255, 180, 100)
  stroke(51)
  strokeWeight(2)

  beginShape(TRIANGLE_STRIP)
  vertex(50,  100)
  vertex(50,  300)
  vertex(150, 50)
  vertex(150, 300)
  vertex(250, 100)
  vertex(250, 300)
  vertex(350, 50)
  vertex(350, 300)
  endShape()

  describe("ribbon of triangles drawn with beginShape(TRIANGLE_STRIP), with stroke")
end

require("L5")

function setup() 
  size(400, 400)
  windowTitle("beginShape(TRIANGLES) example")
  
  fill(0)
  beginShape(TRIANGLES);

  -- Left triangle
  vertex(30, 75);
  vertex(40, 20);
  vertex(50, 75);

  -- Right triangle
  vertex(60, 20);
  vertex(70, 75);
  vertex(80, 20);

  endShape();

  describe("custom shape with beginShape(TRIANGLES) function, vertices and endShape()")
end

require("L5")

function setup()
  size(400, 400)
  windowTitle("texture() example")
  textureMode(NORMAL)

  cat = loadImage("examples/assets/cat.png")

  beginShape(TRIANGLES)
  texture(cat)
  vertex(50,  100, 0,    0.2)
  vertex(50,  300, 0,    1)
  vertex(150, 50,  0.33, 0)
  vertex(150, 300, 0.33, 1)
  vertex(250, 100, 0.67, 0.2)
  vertex(250, 300, 0.67, 1)
  vertex(350, 50,  1,    0)
  vertex(350, 300, 1,    1)
  endShape()

  describe("Wrapping a mesh texture around a custom shape with coordinates specified with u,v")
end

[lee2sman]

Excellent. I just tested all of your example code plus the original versions on Processing's beginShape() reference page.

Before merging, I thought worth considering one minor thing. What do you think we should return for incorrect passed kind parameters and un-implemented QUADS, QUAD_STRIP, TESS? Currently, there isn't error checking for incorrect kind parameter, but in p5.js it will return an error message: ReferenceError: BLARG_STRIP is not defined and in Processing BLARG_STRIP cannot be resolved to a variable. My hunch is that we should add in a kind parameter checking that says basically the same: BLARG_STRIP is not defined. I'm thinking with this added we can then merge.

Afterwards, we also need to update the vertex() reference page (to add info about u,v params) and the beginShape reference pages for info on kind and to add the examples.

[georgeibrahim1]

I wrote this code in L5.lua to handle the error you've mentioned :

function beginShape(_kind)

  if(_kind ~= nil and not L5_env.shapeKinds[_kind]) then -- Lu_env.shapeKinds = {[POINTS]=true, [TRIANGLES]=true, ...}
    error(_kind .. "is not defined" , 2)
  end 
  -- reset custom shape vertices table
  L5_env.vertices = {}
  L5_env.useTexture = false
  L5_env.kind = _kind
end

In Lua, any undefined global variable return nil, so if I called beginShape(NOT_DEFINED_SHAPE), It'll return nil and _kind ~= nil will not pass.

I think to override the returning nil behavior for the undefined variables or it adds overhead?

Do you suggest another way to handle this error?

[lee2sman]

Okay, good to brainstorm this. Unfortunately, I don't think that approach will work since there's no way to catch an undefined variable inside the function. Imagine someone passes an empty variable like BLAH, it will be undefined/nil, which will skip past the _kind ~= nil check in the conditional. Maybe this part should be removed then, unless you have any other solution.

[lee2sman]

To be clear, I'm saying that if _kind ~= nil and not L5_env.shapeKinds[_kind] then error(_kind .. " is not a valid shape kind", 2) end
works with
beginShape(), beginShape(POINTS) and even errors correctly on beginShape("BLAH") but not beginShape(BLAH).
unless I've missed something.

[georgeibrahim1]

I got to this approach

function beginShape(...)

  local n = select('#' , ...)
  local _kind = select(1, ...)

  if(n > 0 and _kind == nil) then
    error(_kind .. "is not defined" , 2)
  end

  if _kind ~= nil and not L5_env.shapeKinds[_kind] then -- to check if you pass strings
    error(_kind .. " is not defined", 2)
  end

  -- reset custom shape vertices table
  L5_env.vertices = {}
  L5_env.useTexture = false
  L5_env.kind = _kind
end

but we can't print the _kind as it's nil, so we can raise error like This shape kind is not defined.

I think we need to override the returning nil behavior for undefined variables to print BLAH is not defined, but it'll affect other places in the code.