Function Reference / combineRuntimeObjectsGroup

Call this function to merge all runtime children objects of a group into a single shape.

prototype

hObject = scene.combineRuntimeObjectsGroup ( hScene, hGroupObject )

It is better to draw 1 object with 1000 triangles, than 1000 objects with only 1 triangle. We usually speak of "number of draw calls", meaning number of time we have to submit a primitives batch to the GPU. Lesser is better. On a computer, you can get a descent frame rate with up to 1000 draw calls (but lesser is better, 1000 is a high limit). But on iPhone 3G for instance, more than 30 draw calls is a maximum (count 10 to get 30 fps).

This function have the same (and more) constraints than the dynamic batcher : to be efficient, your objects have to share the same material (so ideally using a texture atlas). Else, this function will create a mesh subset for each different material, resulting in one draw call per subset. This will never be less efficient, because it will at least removes the overhead implied by the number of objects (for the engine, one object to deal with is better than 1000), but it will be optimal if lot of objects are instances of the same model or have a shared material.

It can be interesting to combine all the objects into only one, but only once. Typically, all games that create levels from XML files with prebuilt blocks.

parameters

hScene - The scene handle
hGroupObject - The group object handle

sample

local hScene = application.getCurrentUserScene ( )
local nRuntimeobjectCount = table.getSize ( this.aRuntimeobject ( ) ) 
if ( nRuntimeobjectCount > 0 )
then
	local hGroup = scene.createRuntimeObject ( hScene, "" )
	for i = 0, nRuntimeobjectCount-1
	do
		local hRuntimeObject = table.getAt ( this.aRuntimeobject ( ), i )
 
		--only objects with shape attribute can be canditate
		if ( hRuntimeObject and  object.isKindOf ( hRuntimeObject, object.kTypeShape ) )
		then
			object.setParent ( hRuntimeObject, hGroup, true )
		end
	end
 
	-- merge all runtime objects into a single big shape
	local hCombinedObject = scene.combineRuntimeObjectsGroup ( hScene, hGroup )		
	if ( hCombinedObject )
	then
		object.setVisible ( hCombinedObject, true )		
		--remove all runtime objects that have been merged
		scene.destroyRuntimeObject ( hScene, hGroup ) 
	else
		log.warning ( "failed to merge runtime objects." )
	end
end

Function Reference / combineRuntimeObjectsGroup

Call this function to merge all runtime children objects of a group into a single shape.

Welcome to the ShiVa Manual user note system

How to enter information

What not to enter

Additional information