Difference between revisions of "love.graphics.newMesh"

(Added missing function variant)
(Updated for 0.10.0)
Line 1: Line 1:
 
{{newin|[[0.9.0]]|090|type=function}}
 
{{newin|[[0.9.0]]|090|type=function}}
 
Creates a new [[Mesh]].
 
Creates a new [[Mesh]].
 +
 +
Use [[Mesh:setTexture]] if the Mesh should be textured with an [[Image]] or [[Canvas]] when it's drawn.
 +
 
{{newobjectnotice}}
 
{{newobjectnotice}}
 +
 +
== Function ==
 +
{{newin|[[0.10.0]]|100|type=variant}}
 +
Creates a standard Mesh with the specified vertices.
 +
=== Synopsis ===
 +
<source lang="lua">
 +
mesh = love.graphics.newMesh( vertices, mode, usage )
 +
</source>
 +
=== Arguments ===
 +
{{param|table|vertices|The table filled with vertex information tables for each vertex as follows:}}
 +
{{subparam|number|[1]|The position of the vertex on the x-axis.}}
 +
{{subparam|number|[2]|The position of the vertex on the y-axis.}}
 +
{{subparam|number|[3] (0)|The u texture coordinate of the vertex. Texture coordinates are normally in the range of [0, 1], but can be greater or less (see [[WrapMode]].)}}
 +
{{subparam|number|[4] (0)|The v texture coordinate of the vertex. Texture coordinates are normally in the range of [0, 1], but can be greater or less (see [[WrapMode]].)}}
 +
{{subparam|number|[5] (255)|The red component of the vertex color.}}
 +
{{subparam|number|[6] (255)|The green component of the vertex color.}}
 +
{{subparam|number|[7] (255)|The blue component of the vertex color.}}
 +
{{subparam|number|[8] (255)|The alpha component of the vertex color.}}
 +
{{param|MeshDrawMode|mode ("fan")|How the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.}}
 +
{{param|SpriteBatchUsage|usage ("dynamic")|The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.}}
 +
=== Returns ===
 +
{{param|Mesh|mesh|The new mesh.}}
 +
 +
== Function ==
 +
{{newin|[[0.10.0]]|100|type=variant}}
 +
Creates a standard Mesh with the specified number of vertices.
 +
=== Synopsis ===
 +
<source lang="lua">
 +
mesh = love.graphics.newMesh( vertexcount, mode, usage )
 +
</source>
 +
=== Arguments ===
 +
{{param|number|vertexcount|The total number of vertices the Mesh will use. Each vertex is initialized to <code>{0,0, 0,0, 255,255,255,255}</code>.}}
 +
{{param|MeshDrawMode|mode ("fan")|How the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.}}
 +
{{param|SpriteBatchUsage|usage ("dynamic")|The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.}}
 +
=== Returns ===
 +
{{param|Mesh|mesh|The new mesh.}}
 +
=== Notes ===
 +
[[Mesh:setVertices]] or [[Mesh:setVertex]] and [[Mesh:setDrawRange]] can be used to specify vertex information once the Mesh is created.
 +
 +
== Function ==
 +
{{newin|[[0.10.0]]|100|type=variant}}
 +
Creates a Mesh with custom vertex attributes and the specified vertex data.
 +
=== Synopsis ===
 +
<source lang="lua">
 +
mesh = love.graphics.newMesh( vertexformat, vertices, mode, usage )
 +
</source>
 +
=== Arguments ===
 +
{{param|table|vertexformat|A table in the form of <code>{attribute, ...}</code>. Each attribute is a table which specifies a custom vertex attribute used for each vertex.}}
 +
{{subparam|table|attribute|A table containing the attribute's name, it's [[AttributeDataType|data type]], and the number of components in the attribute, in the form of <code>{name, datatype, components}</code>.}}
 +
{{subparam|table|...|Additional vertex attribute format tables.}}
 +
{{param|table|vertices|The table filled with vertex information tables for each vertex, in the form of <code>{vertex, ...}</code> where each vertex is a table in the form of <code>{attributecomponent, ...}</code>.}}
 +
{{subparam|number|attributecomponent|The first component of the first vertex attribute in the vertex.}}
 +
{{subparam|number|...|Additional components of all vertex attributes in the vertex.}}
 +
{{param|MeshDrawMode|mode ("fan")|How the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.}}
 +
{{param|SpriteBatchUsage|usage ("dynamic")|The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.}}
 +
=== Returns ===
 +
{{param|Mesh|mesh|The new mesh.}}
 +
=== Notes ===
 +
The values in each vertex table are in the same order as the vertex attributes in the specified vertex format. If no value is supplied for a specific vertex attribute component, it will be set to a default value of 0 if its [[AttributeDataType|data type]] is "float", or 255 if its data type is "byte".
 +
 +
If a custom vertex attribute uses the name "VertexPosition", "VertexTexCoord", or "VertexColor", then the vertex data for that vertex attribute will be used for the standard vertex positions, texture coordinates, or vertex colors respectively, when drawing the Mesh. Otherwise a [[Shader|Vertex Shader]] is required in order to make use of the vertex attribute when the Mesh is drawn.
 +
 +
A Mesh '''must''' have a "VertexPosition" attribute in order to be drawn, but it can be attached from a different Mesh via [[Mesh:attachAttribute]].
 +
 +
To use a custom named vertex attribute in a Vertex Shader, it must be declared as an <code>attribute</code> variable of the same name. Variables can be sent from Vertex Shader code to Pixel Shader code by making a <code>varying</code> variable. For example:
 +
 +
''Vertex Shader code''
 +
<source lang="glsl">
 +
attribute vec2 CoolVertexAttribute;
 +
 +
varying vec2 CoolVariable;
 +
 +
vec4 position(mat4 transform_projection, vec4 vertex_position)
 +
{
 +
    CoolVariable = CoolVertexAttribute;
 +
    return transform_projection * vertex_position;
 +
}
 +
</source>
 +
''Pixel Shader code''
 +
<source lang="glsl">
 +
varying vec2 CoolVariable;
 +
 +
vec4 effect(vec4 color, Image tex, vec2 texcoord, vec2 pixcoord)
 +
{
 +
    vec4 texcolor = Texel(tex, texcoord + CoolVariable);
 +
    return texcolor * color;
 +
}
 +
</source>
 +
 
== Function ==
 
== Function ==
 +
{{newin|[[0.10.0]]|100|type=variant}}
 +
Creates a Mesh with custom vertex attributes and the specified number of vertices.
 +
=== Synopsis ===
 +
<source lang="lua">
 +
mesh = love.graphics.newMesh( vertexformat, vertexcount, mode, usage )
 +
</source>
 +
=== Arguments ===
 +
{{param|table|vertexformat|A table in the form of <code>{attribute, ...}</code>. Each attribute is a table which specifies a custom vertex attribute used for each vertex.}}
 +
{{subparam|table|attribute|A table containing the attribute's name, it's [[AttributeDataType|data type]], and the number of components in the attribute, in the form of <code>{name, datatype, components}</code>.}}
 +
{{subparam|table|...|Additional vertex attribute format tables.}}
 +
{{param|number|vertexcount|The total number of vertices the Mesh will use.}}
 +
{{param|MeshDrawMode|mode ("fan")|How the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.}}
 +
{{param|SpriteBatchUsage|usage ("dynamic")|The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.}}
 +
=== Returns ===
 +
{{param|Mesh|mesh|The new mesh.}}
 +
=== Notes ===
 +
Each vertex attribute component is initialized to 0 if its data type is "float", or 255 if its data type is "byte". [[Mesh:setVertices]] or [[Mesh:setVertex]] and [[Mesh:setDrawRange]] can be used to specify vertex information once the Mesh is created.
 +
 +
If a custom vertex attribute uses the name "VertexPosition", "VertexTexCoord", or "VertexColor", then the vertex data for that vertex attribute will be used for the standard vertex positions, texture coordinates, or vertex colors respectively, when drawing the Mesh. Otherwise a [[Shader|Vertex Shader]] is required in order to make use of the vertex attribute when the Mesh is drawn.
 +
 +
A Mesh '''must''' have a "VertexPosition" attribute in order to be drawn, but it can be attached from a different Mesh via [[Mesh:attachAttribute]].
 +
 +
== Function ==
 +
{{oldin|[[0.10.0]]|100|type=variant}}
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
Line 24: Line 140:
 
== Function ==
 
== Function ==
 
{{newin|[[0.9.1]]|091|type=variant}}
 
{{newin|[[0.9.1]]|091|type=variant}}
 +
{{oldin|[[0.10.0]]|100|type=variant}}
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
Line 69: Line 186:
 
},
 
},
 
}
 
}
+
 
 
-- the Mesh DrawMode "fan" works well for 4-vertex Meshes.
 
-- the Mesh DrawMode "fan" works well for 4-vertex Meshes.
mesh = love.graphics.newMesh(vertices, image, "fan")
+
mesh = love.graphics.newMesh(vertices, "fan")
 +
        mesh:setTexture(image)
 
end
 
end
  
Line 105: Line 223:
 
 
 
-- The "fan" draw mode is perfect for our circle.
 
-- The "fan" draw mode is perfect for our circle.
return love.graphics.newMesh(vertices, image, "fan")
+
local mesh = love.graphics.newMesh(vertices, "fan")
 +
        mesh:setTexture(image)
 +
 
 +
        return mesh
 
end
 
end
  
Line 142: Line 263:
 
end
 
end
 
 
-- The "fan" draw mode is perfect for our circle. We aren't texturing it, so we leave that argument as nil.
+
-- The "fan" draw mode is perfect for our circle.
return love.graphics.newMesh(vertices, nil, "fan")
+
return love.graphics.newMesh(vertices, "fan")
 
end
 
end
  

Revision as of 03:22, 20 December 2015

Available since LÖVE 0.9.0
This function is not supported in earlier versions.

Creates a new Mesh.

Use Mesh:setTexture if the Mesh should be textured with an Image or Canvas when it's drawn.


O.png This function can be slow if it is called repeatedly, such as from love.update or love.draw. If you need to use a specific resource often, create it once and store it somewhere it can be reused!  



Function

Available since LÖVE 0.10.0
This variant is not supported in earlier versions.

Creates a standard Mesh with the specified vertices.

Synopsis

mesh = love.graphics.newMesh( vertices, mode, usage )

Arguments

table vertices
The table filled with vertex information tables for each vertex as follows:
number [1]
The position of the vertex on the x-axis.
number [2]
The position of the vertex on the y-axis.
number [3] (0)
The u texture coordinate of the vertex. Texture coordinates are normally in the range of [0, 1], but can be greater or less (see WrapMode.)
number [4] (0)
The v texture coordinate of the vertex. Texture coordinates are normally in the range of [0, 1], but can be greater or less (see WrapMode.)
number [5] (255)
The red component of the vertex color.
number [6] (255)
The green component of the vertex color.
number [7] (255)
The blue component of the vertex color.
number [8] (255)
The alpha component of the vertex color.
MeshDrawMode mode ("fan")
How the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.
SpriteBatchUsage usage ("dynamic")
The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.

Returns

Mesh mesh
The new mesh.

Function

Available since LÖVE 0.10.0
This variant is not supported in earlier versions.

Creates a standard Mesh with the specified number of vertices.

Synopsis

mesh = love.graphics.newMesh( vertexcount, mode, usage )

Arguments

number vertexcount
The total number of vertices the Mesh will use. Each vertex is initialized to {0,0, 0,0, 255,255,255,255}.
MeshDrawMode mode ("fan")
How the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.
SpriteBatchUsage usage ("dynamic")
The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.

Returns

Mesh mesh
The new mesh.

Notes

Mesh:setVertices or Mesh:setVertex and Mesh:setDrawRange can be used to specify vertex information once the Mesh is created.

Function

Available since LÖVE 0.10.0
This variant is not supported in earlier versions.

Creates a Mesh with custom vertex attributes and the specified vertex data.

Synopsis

mesh = love.graphics.newMesh( vertexformat, vertices, mode, usage )

Arguments

table vertexformat
A table in the form of {attribute, ...}. Each attribute is a table which specifies a custom vertex attribute used for each vertex.
table attribute
A table containing the attribute's name, it's data type, and the number of components in the attribute, in the form of {name, datatype, components}.
table ...
Additional vertex attribute format tables.
table vertices
The table filled with vertex information tables for each vertex, in the form of {vertex, ...} where each vertex is a table in the form of {attributecomponent, ...}.
number attributecomponent
The first component of the first vertex attribute in the vertex.
number ...
Additional components of all vertex attributes in the vertex.
MeshDrawMode mode ("fan")
How the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.
SpriteBatchUsage usage ("dynamic")
The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.

Returns

Mesh mesh
The new mesh.

Notes

The values in each vertex table are in the same order as the vertex attributes in the specified vertex format. If no value is supplied for a specific vertex attribute component, it will be set to a default value of 0 if its data type is "float", or 255 if its data type is "byte".

If a custom vertex attribute uses the name "VertexPosition", "VertexTexCoord", or "VertexColor", then the vertex data for that vertex attribute will be used for the standard vertex positions, texture coordinates, or vertex colors respectively, when drawing the Mesh. Otherwise a Vertex Shader is required in order to make use of the vertex attribute when the Mesh is drawn.

A Mesh must have a "VertexPosition" attribute in order to be drawn, but it can be attached from a different Mesh via Mesh:attachAttribute.

To use a custom named vertex attribute in a Vertex Shader, it must be declared as an attribute variable of the same name. Variables can be sent from Vertex Shader code to Pixel Shader code by making a varying variable. For example:

Vertex Shader code

attribute vec2 CoolVertexAttribute;

varying vec2 CoolVariable;

vec4 position(mat4 transform_projection, vec4 vertex_position)
{
    CoolVariable = CoolVertexAttribute;
    return transform_projection * vertex_position;
}

Pixel Shader code

varying vec2 CoolVariable;

vec4 effect(vec4 color, Image tex, vec2 texcoord, vec2 pixcoord)
{
    vec4 texcolor = Texel(tex, texcoord + CoolVariable);
    return texcolor * color;
}

Function

Available since LÖVE 0.10.0
This variant is not supported in earlier versions.

Creates a Mesh with custom vertex attributes and the specified number of vertices.

Synopsis

mesh = love.graphics.newMesh( vertexformat, vertexcount, mode, usage )

Arguments

table vertexformat
A table in the form of {attribute, ...}. Each attribute is a table which specifies a custom vertex attribute used for each vertex.
table attribute
A table containing the attribute's name, it's data type, and the number of components in the attribute, in the form of {name, datatype, components}.
table ...
Additional vertex attribute format tables.
number vertexcount
The total number of vertices the Mesh will use.
MeshDrawMode mode ("fan")
How the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.
SpriteBatchUsage usage ("dynamic")
The expected usage of the Mesh. The specified usage mode affects the Mesh's memory usage and performance.

Returns

Mesh mesh
The new mesh.

Notes

Each vertex attribute component is initialized to 0 if its data type is "float", or 255 if its data type is "byte". Mesh:setVertices or Mesh:setVertex and Mesh:setDrawRange can be used to specify vertex information once the Mesh is created.

If a custom vertex attribute uses the name "VertexPosition", "VertexTexCoord", or "VertexColor", then the vertex data for that vertex attribute will be used for the standard vertex positions, texture coordinates, or vertex colors respectively, when drawing the Mesh. Otherwise a Vertex Shader is required in order to make use of the vertex attribute when the Mesh is drawn.

A Mesh must have a "VertexPosition" attribute in order to be drawn, but it can be attached from a different Mesh via Mesh:attachAttribute.

Function

Removed in LÖVE 0.10.0
This variant is not supported in that and later versions.

Synopsis

mesh = love.graphics.newMesh( vertices, texture, mode )

Arguments

table vertices
The table filled with vertex information tables for each vertex as follows:
number [1]
The position of the vertex on the x-axis.
number [2]
The position of the vertex on the y-axis.
number [3]
The u texture coordinate. Texture coordinates are normally in the range of [0, 1], but can be greater or less (see WrapMode.)
number [4]
The v texture coordinate. Texture coordinates are normally in the range of [0, 1], but can be greater or less (see WrapMode.)
number [5] (255)
The red color component.
number [6] (255)
The green color component.
number [7] (255)
The blue color component.
number [8] (255)
The alpha color component.
Texture texture (nil)
The Image or Canvas to use when drawing the Mesh. May be nil to use no texture.
MeshDrawMode mode ("fan")
How the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.

Returns

Mesh mesh
The new mesh.

Function

Available since LÖVE 0.9.1
This variant is not supported in earlier versions.
Removed in LÖVE 0.10.0
This variant is not supported in that and later versions.

Synopsis

mesh = love.graphics.newMesh( vertexcount, texture, mode )

Arguments

number vertexcount
The total number of vertices the Mesh will use. Each vertex is initialized to {0,0, 0,0, 255,255,255,255}.
Texture texture (nil)
The Image or Canvas to use when drawing the Mesh. May be nil to use no texture.
MeshDrawMode mode ("fan")
How the vertices are used when drawing. The default mode "fan" is sufficient for simple convex polygons.

Returns

Mesh mesh
The new mesh.

Notes

Mesh:setVertices or Mesh:setVertex and Mesh:setDrawRange can be used to specify vertex information once the Mesh is created.

Examples

Creates and draws a Mesh identical to a normal drawn image but with different colors at each corner

function love.load()
	image = love.graphics.newImage("pig.png")
	
	local vertices = {
		{
			-- top-left corner (red-tinted)
			0, 0, -- position of the vertex
			0, 0, -- texture coordinate at the vertex position
			255, 0, 0, -- color of the vertex
		},
		{
			-- top-right corner (green-tinted)
			image:getWidth(), 0,
			1, 0, -- texture coordinates are in the range of [0, 1]
			0, 255, 0
		},
		{
			-- bottom-right corner (blue-tinted)
			image:getWidth(), image:getHeight(),
			1, 1,
			0, 0, 255
		},
		{
			-- bottom-left corner (yellow-tinted)
			0, image:getHeight(),
			0, 1,
			255, 255, 0
		},
	}

	-- the Mesh DrawMode "fan" works well for 4-vertex Meshes.
	mesh = love.graphics.newMesh(vertices, "fan")
        mesh:setTexture(image)
end

function love.draw()
	love.graphics.draw(mesh, 0, 0)
end

Creates and draws a textured circle with a red tint at the center.

function CreateTexturedCircle(image, segments)
	segments = segments or 40
	local vertices = {}
	
	-- The first vertex is at the center, and has a red tint. We're centering the circle around the origin (0, 0).
	table.insert(vertices, {0, 0, 0.5, 0.5, 255, 0, 0})
	
	-- Create the vertices at the edge of the circle.
	for i=0, segments do
		local angle = (i / segments) * math.pi * 2

		-- Unit-circle.
		local x = math.cos(angle)
		local y = math.sin(angle)
		
		-- Our position is in the range of [-1, 1] but we want the texture coordinate to be in the range of [0, 1].
		local u = (x + 1) * 0.5
		local v = (y + 1) * 0.5
		
		-- The per-vertex color defaults to white.
		table.insert(vertices, {x, y, u, v})
	end
	
	-- The "fan" draw mode is perfect for our circle.
	local mesh = love.graphics.newMesh(vertices, "fan")
        mesh:setTexture(image)

        return mesh
end

function love.load()
	image = love.graphics.newImage("pig.png")
	mesh = CreateTexturedCircle(image)
end

function love.draw()
	local radius = 100
	local mx, my = love.mouse.getPosition()
	
	-- We created a unit-circle, so we can use the scale parameter for the radius directly.
	love.graphics.draw(mesh, mx, my, 0, radius, radius)
end

Creates a circle and draws it more efficiently than love.graphics.circle.

function CreateCircle(segments)
	segments = segments or 40
	local vertices = {}
	
	-- The first vertex is at the origin (0, 0) and will be the center of the circle.
	table.insert(vertices, {0, 0})
	
	-- Create the vertices at the edge of the circle.
	for i=0, segments do
		local angle = (i / segments) * math.pi * 2

		-- Unit-circle.
		local x = math.cos(angle)
		local y = math.sin(angle)

		table.insert(vertices, {x, y})
	end
	
	-- The "fan" draw mode is perfect for our circle.
	return love.graphics.newMesh(vertices, "fan")
end

function love.load()
	mesh = CreateCircle()
end

function love.draw()
	local radius = 100
	local mx, my = love.mouse.getPosition()
	
	-- We created a unit-circle, so we can use the scale parameter for the radius directly.
	love.graphics.draw(mesh, mx, my, 0, radius, radius)
end

See Also


Other Languages