summaryrefslogtreecommitdiff
path: root/src/lib/evas/Evas_Common.h
diff options
context:
space:
mode:
authorsubhransu <subhransu@subhransu-System.(none)>2014-04-14 19:03:47 +0900
committerChunEon Park <hermet@hermet.pe.kr>2014-04-25 16:58:47 +0900
commite84e28fc225f46f5e5e25bf23677a647a75ea3c9 (patch)
treedcd8b36a1ae6da7d44fb141e2f0ee7186082c66a /src/lib/evas/Evas_Common.h
parent86ce491a862296c92bbf377cc11faf93d7a7efe7 (diff)
Evas_3D : Eolian change
Conflicts: src/Makefile_Evas.am src/lib/evas/Evas_3D.h src/lib/evas/Evas_Eo.h
Diffstat (limited to 'src/lib/evas/Evas_Common.h')
-rw-r--r--src/lib/evas/Evas_Common.h2273
1 files changed, 2211 insertions, 62 deletions
diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h
index 88c4b61bed..ebf3e8e0bc 100644
--- a/src/lib/evas/Evas_Common.h
+++ b/src/lib/evas/Evas_Common.h
@@ -806,18 +806,18 @@ typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type t
806 806
807/** 807/**
808 * Get the path for the cserve binary to execute 808 * Get the path for the cserve binary to execute
809 * 809 *
810 * There is little need for anyone except a desktop environment to call this. 810 * There is little need for anyone except a desktop environment to call this.
811 * This can be called before evas_init() has been called. It will try and find 811 * This can be called before evas_init() has been called. It will try and find
812 * the full path to the to the cserve binary to run to provide cserve image 812 * the full path to the to the cserve binary to run to provide cserve image
813 * and font caching services for evas. 813 * and font caching services for evas.
814 * 814 *
815 * @return NULL if error, or a string with the full path to the cserve binary. 815 * @return NULL if error, or a string with the full path to the cserve binary.
816 * 816 *
817 * @since 1.8 817 * @since 1.8
818 */ 818 */
819EAPI const char *evas_cserve_path_get(void); 819EAPI const char *evas_cserve_path_get(void);
820 820
821/** 821/**
822 * Initialize Evas 822 * Initialize Evas
823 * 823 *
@@ -1272,13 +1272,13 @@ EAPI void evas_render_updates_free(Eina_List *updates);
1272 1272
1273/** 1273/**
1274 * Add a new device type 1274 * Add a new device type
1275 * 1275 *
1276 * @param e The canvas to create the device node for. 1276 * @param e The canvas to create the device node for.
1277 * 1277 *
1278 * Adds a new device nod to the given canvas @p e. All devices created as 1278 * Adds a new device nod to the given canvas @p e. All devices created as
1279 * part of the canvas @p e will automatically be deleted when the canvas 1279 * part of the canvas @p e will automatically be deleted when the canvas
1280 * is freed. 1280 * is freed.
1281 * 1281 *
1282 * @see evas_device_del 1282 * @see evas_device_del
1283 * @since 1.8 1283 * @since 1.8
1284 */ 1284 */
@@ -1286,73 +1286,73 @@ EAPI Evas_Device *evas_device_add(Evas *e);
1286 1286
1287/** 1287/**
1288 * Delete a new device type 1288 * Delete a new device type
1289 * 1289 *
1290 * @see evas_device_add 1290 * @see evas_device_add
1291 * @see evas_device_push 1291 * @see evas_device_push
1292 * @see evas_device_pop 1292 * @see evas_device_pop
1293 * @since 1.8 1293 * @since 1.8
1294 */ 1294 */
1295EAPI void evas_device_del(Evas_Device *dev); 1295EAPI void evas_device_del(Evas_Device *dev);
1296 1296
1297/** 1297/**
1298 * Push the current context device onto the device stack 1298 * Push the current context device onto the device stack
1299 * 1299 *
1300 * @param e The canvas to push the device on to 1300 * @param e The canvas to push the device on to
1301 * @param dev The device to push. 1301 * @param dev The device to push.
1302 * 1302 *
1303 * This pushes the given device @p dev onto the stack for the canvas @p e 1303 * This pushes the given device @p dev onto the stack for the canvas @p e
1304 * resulting in the dev pointer in all events that get fed to the canvas 1304 * resulting in the dev pointer in all events that get fed to the canvas
1305 * being the device at the top of the device stack for that canvas. 1305 * being the device at the top of the device stack for that canvas.
1306 * 1306 *
1307 * If a device is pushed onto the device stack, it will not be deleted 1307 * If a device is pushed onto the device stack, it will not be deleted
1308 * until a canvas free OR until it has been popped from the stack even if 1308 * until a canvas free OR until it has been popped from the stack even if
1309 * evas_device_del() is called. 1309 * evas_device_del() is called.
1310 * 1310 *
1311 * The device @p dev must have been created as a device for the canvas it 1311 * The device @p dev must have been created as a device for the canvas it
1312 * is pushed onto (and not another canvas). 1312 * is pushed onto (and not another canvas).
1313 * 1313 *
1314 * Example: 1314 * Example:
1315 * @code 1315 * @code
1316 * evas_device_push(canvas, dev); 1316 * evas_device_push(canvas, dev);
1317 * evas_event_feed_mouse_move(canvas, 20, 30, 0, NULL); 1317 * evas_event_feed_mouse_move(canvas, 20, 30, 0, NULL);
1318 * evas_device_pop(canvas); 1318 * evas_device_pop(canvas);
1319 * @endcode 1319 * @endcode
1320 * 1320 *
1321 * @see evas_device_pop 1321 * @see evas_device_pop
1322 * @since 1.8 1322 * @since 1.8
1323 */ 1323 */
1324EAPI void evas_device_push(Evas *e, Evas_Device *dev); 1324EAPI void evas_device_push(Evas *e, Evas_Device *dev);
1325 1325
1326/** 1326/**
1327 * This pops the top of the device stack for the canvas 1327 * This pops the top of the device stack for the canvas
1328 * 1328 *
1329 * @param e The canvas to pop the device stack from 1329 * @param e The canvas to pop the device stack from
1330 * 1330 *
1331 * This pops the top of the device stack making the current device context 1331 * This pops the top of the device stack making the current device context
1332 * used for device events being what is now at the top of the stack after 1332 * used for device events being what is now at the top of the stack after
1333 * popping. 1333 * popping.
1334 * 1334 *
1335 * @see evas_device_push 1335 * @see evas_device_push
1336 * @since 1.8 1336 * @since 1.8
1337 */ 1337 */
1338EAPI void evas_device_pop(Evas *e); 1338EAPI void evas_device_pop(Evas *e);
1339 1339
1340/** 1340/**
1341 * List all current devices attached to the given canvas and/or device 1341 * List all current devices attached to the given canvas and/or device
1342 * 1342 *
1343 * @param e The canvas to query for a device list 1343 * @param e The canvas to query for a device list
1344 * @param dev A specific device inside the canvas to query for child devices or NULL if just querying the base canvas devices 1344 * @param dev A specific device inside the canvas to query for child devices or NULL if just querying the base canvas devices
1345 * @return An internal list of Evas_Device pointers, or NULL if no devices are found 1345 * @return An internal list of Evas_Device pointers, or NULL if no devices are found
1346 * 1346 *
1347 * This will list all devices belonging to a specific evas canvas @p e, at the 1347 * This will list all devices belonging to a specific evas canvas @p e, at the
1348 * top-level in the device tree if @p dev passed in is NULL. If @p dev is 1348 * top-level in the device tree if @p dev passed in is NULL. If @p dev is
1349 * a valid device for the given canvas @p e, then a list of child devices 1349 * a valid device for the given canvas @p e, then a list of child devices
1350 * of @p dev will be returned, allowing you to walk the device tree. 1350 * of @p dev will be returned, allowing you to walk the device tree.
1351 * 1351 *
1352 * The list returned is only valid so long as no changes are made to the 1352 * The list returned is only valid so long as no changes are made to the
1353 * device tree in the given canvas @p e. If there are no devices or children 1353 * device tree in the given canvas @p e. If there are no devices or children
1354 * then NULL is returned. 1354 * then NULL is returned.
1355 * 1355 *
1356 * @see evas_device_parent_get 1356 * @see evas_device_parent_get
1357 * @see evas_device_name_get 1357 * @see evas_device_name_get
1358 * @see evas_device_description_get 1358 * @see evas_device_description_get
@@ -1365,164 +1365,164 @@ EAPI const Eina_List *evas_device_list(Evas *e, const Evas_Device *dev);
1365 1365
1366/** 1366/**
1367 * Set the name of a device as a string 1367 * Set the name of a device as a string
1368 * 1368 *
1369 * @p dev The device to set the name of 1369 * @p dev The device to set the name of
1370 * @p name The name string as a readable C UTF8 string 1370 * @p name The name string as a readable C UTF8 string
1371 * 1371 *
1372 * @since 1.8 1372 * @since 1.8
1373 */ 1373 */
1374EAPI void evas_device_name_set(Evas_Device *dev, const char *name); 1374EAPI void evas_device_name_set(Evas_Device *dev, const char *name);
1375 1375
1376/** 1376/**
1377 * Get the name of a device 1377 * Get the name of a device
1378 * 1378 *
1379 * @p dev The device to query 1379 * @p dev The device to query
1380 * @return The device name string or NULL if none is set 1380 * @return The device name string or NULL if none is set
1381 * 1381 *
1382 * This gets the name set by evas_device_name_set(). This is a readable UTF8 1382 * This gets the name set by evas_device_name_set(). This is a readable UTF8
1383 * C string, or NULL if no name is set. 1383 * C string, or NULL if no name is set.
1384 * 1384 *
1385 * The name should be a short name like "Wireless Mouse", "Joystick", 1385 * The name should be a short name like "Wireless Mouse", "Joystick",
1386 * "Finger", "Keyboard" or "Numberpad" etc. 1386 * "Finger", "Keyboard" or "Numberpad" etc.
1387 * 1387 *
1388 * @since 1.8 1388 * @since 1.8
1389 */ 1389 */
1390EAPI const char *evas_device_name_get(const Evas_Device *dev); 1390EAPI const char *evas_device_name_get(const Evas_Device *dev);
1391 1391
1392/** 1392/**
1393 * Set the description of a device as a string 1393 * Set the description of a device as a string
1394 * 1394 *
1395 * @p dev The device to set the description of 1395 * @p dev The device to set the description of
1396 * @p name The description string as a readable C UTF8 string 1396 * @p name The description string as a readable C UTF8 string
1397 * 1397 *
1398 * @since 1.8 1398 * @since 1.8
1399 */ 1399 */
1400EAPI void evas_device_description_set(Evas_Device *dev, const char *desc); 1400EAPI void evas_device_description_set(Evas_Device *dev, const char *desc);
1401 1401
1402/** 1402/**
1403 * Get the description of a device 1403 * Get the description of a device
1404 * 1404 *
1405 * @p dev The device to query 1405 * @p dev The device to query
1406 * @return The device description string or NULL if none is set 1406 * @return The device description string or NULL if none is set
1407 * 1407 *
1408 * This gets the description set by evas_device_description_set(). This is 1408 * This gets the description set by evas_device_description_set(). This is
1409 * a readable UTF8 C string, or NULL if no description is set. 1409 * a readable UTF8 C string, or NULL if no description is set.
1410 * 1410 *
1411 * A description is meant to be a longer string describing the device so a 1411 * A description is meant to be a longer string describing the device so a
1412 * human may make sense of it. For example "Wireless 6 button mouse in Black 1412 * human may make sense of it. For example "Wireless 6 button mouse in Black
1413 * with red buttons" would be a good description, so a user may identify 1413 * with red buttons" would be a good description, so a user may identify
1414 * precisely which device is being talked about. 1414 * precisely which device is being talked about.
1415 * 1415 *
1416 * @since 1.8 1416 * @since 1.8
1417 */ 1417 */
1418EAPI const char *evas_device_description_get(const Evas_Device *dev); 1418EAPI const char *evas_device_description_get(const Evas_Device *dev);
1419 1419
1420/** 1420/**
1421 * Set the parent of a device 1421 * Set the parent of a device
1422 * 1422 *
1423 * @p dev The device to set the parent of 1423 * @p dev The device to set the parent of
1424 * @p parent The new parent device 1424 * @p parent The new parent device
1425 * 1425 *
1426 * This sets the parent of a device @p dev to the parent given by @p parent. 1426 * This sets the parent of a device @p dev to the parent given by @p parent.
1427 * If the device already has a parent, it is removed from that parent's list. 1427 * If the device already has a parent, it is removed from that parent's list.
1428 * If @p parent is NULL then the device is unparented and placed back as a 1428 * If @p parent is NULL then the device is unparented and placed back as a
1429 * root device in the canvas. 1429 * root device in the canvas.
1430 * 1430 *
1431 * When a device is deleted with evas_device_del(), all children are also 1431 * When a device is deleted with evas_device_del(), all children are also
1432 * deleted along with it. 1432 * deleted along with it.
1433 * 1433 *
1434 * @see evas_device_del 1434 * @see evas_device_del
1435 * @see evas_device_parent_get 1435 * @see evas_device_parent_get
1436 * @see evas_device_list 1436 * @see evas_device_list
1437 * 1437 *
1438 * @since 1.8 1438 * @since 1.8
1439 */ 1439 */
1440EAPI void evas_device_parent_set(Evas_Device *dev, Evas_Device *parent); 1440EAPI void evas_device_parent_set(Evas_Device *dev, Evas_Device *parent);
1441 1441
1442/** 1442/**
1443 * Get the parent of a device 1443 * Get the parent of a device
1444 * 1444 *
1445 * @param dev The device to query 1445 * @param dev The device to query
1446 * @return The parent device or NULL if it is a toplevel 1446 * @return The parent device or NULL if it is a toplevel
1447 * 1447 *
1448 * This returns the parent device of any given device entry, or NULL if no 1448 * This returns the parent device of any given device entry, or NULL if no
1449 * parent device exists (is a toplevel device). 1449 * parent device exists (is a toplevel device).
1450 * 1450 *
1451 * @since 1.8 1451 * @since 1.8
1452 */ 1452 */
1453EAPI const Evas_Device *evas_device_parent_get(const Evas_Device *dev); 1453EAPI const Evas_Device *evas_device_parent_get(const Evas_Device *dev);
1454 1454
1455/** 1455/**
1456 * Set the major class of device 1456 * Set the major class of device
1457 * 1457 *
1458 * @param dev The device whose class to set 1458 * @param dev The device whose class to set
1459 * @param clas The class to set it to 1459 * @param clas The class to set it to
1460 * 1460 *
1461 * This sets the "primary" class of device (a broad thing like mouse, keyboard, 1461 * This sets the "primary" class of device (a broad thing like mouse, keyboard,
1462 * touch, pen etc.). 1462 * touch, pen etc.).
1463 * 1463 *
1464 * @since 1.8 1464 * @since 1.8
1465 */ 1465 */
1466EAPI void evas_device_class_set(Evas_Device *dev, Evas_Device_Class clas); 1466EAPI void evas_device_class_set(Evas_Device *dev, Evas_Device_Class clas);
1467 1467
1468/** 1468/**
1469 * Get the major class of a device 1469 * Get the major class of a device
1470 * 1470 *
1471 * @param dev The devise to query 1471 * @param dev The devise to query
1472 * @return The device class to set 1472 * @return The device class to set
1473 * 1473 *
1474 * This sets the device class set by evas_device_class_set(). 1474 * This sets the device class set by evas_device_class_set().
1475 * 1475 *
1476 * @since 1.8 1476 * @since 1.8
1477 */ 1477 */
1478EAPI Evas_Device_Class evas_device_class_get(const Evas_Device *dev); 1478EAPI Evas_Device_Class evas_device_class_get(const Evas_Device *dev);
1479 1479
1480/** 1480/**
1481 * Set the sub-class of a device 1481 * Set the sub-class of a device
1482 * 1482 *
1483 * @param dev The device to modify 1483 * @param dev The device to modify
1484 * @param clas The sub-class to set 1484 * @param clas The sub-class to set
1485 * 1485 *
1486 * This sets the sub-class of a device whihc gives much more detailed usage 1486 * This sets the sub-class of a device whihc gives much more detailed usage
1487 * within a broader category. 1487 * within a broader category.
1488 * 1488 *
1489 * @since 1.8 1489 * @since 1.8
1490 */ 1490 */
1491EAPI void evas_device_subclass_set(Evas_Device *dev, Evas_Device_Subclass clas); 1491EAPI void evas_device_subclass_set(Evas_Device *dev, Evas_Device_Subclass clas);
1492 1492
1493/** 1493/**
1494 * Get the device sub-class 1494 * Get the device sub-class
1495 * 1495 *
1496 * @param dev The device to query 1496 * @param dev The device to query
1497 * @return The device sub-class set by evas_device_subclass_set(). 1497 * @return The device sub-class set by evas_device_subclass_set().
1498 * 1498 *
1499 * @since 1.8 1499 * @since 1.8
1500 */ 1500 */
1501EAPI Evas_Device_Subclass evas_device_subclass_get(const Evas_Device *dev); 1501EAPI Evas_Device_Subclass evas_device_subclass_get(const Evas_Device *dev);
1502 1502
1503/** 1503/**
1504 * Set the emulation source device 1504 * Set the emulation source device
1505 * 1505 *
1506 * @param dev The device being emulated 1506 * @param dev The device being emulated
1507 * @param src The primary source device producing events in the emulated device 1507 * @param src The primary source device producing events in the emulated device
1508 * 1508 *
1509 * Devices may not be real, but may be emulated by listening to input on other 1509 * Devices may not be real, but may be emulated by listening to input on other
1510 * devices and modifying or interpeting it to generate output on an emulated 1510 * devices and modifying or interpeting it to generate output on an emulated
1511 * device (example a fingeron a touchscreen will often emulate a mouse when 1511 * device (example a fingeron a touchscreen will often emulate a mouse when
1512 * it presses). This allows you to set which device primarily emulates @p dev 1512 * it presses). This allows you to set which device primarily emulates @p dev
1513 * so the user can choose to ignore events from emulated devices if they also 1513 * so the user can choose to ignore events from emulated devices if they also
1514 * pay attention to source device events for example. 1514 * pay attention to source device events for example.
1515 * 1515 *
1516 * @since 1.8 1516 * @since 1.8
1517 */ 1517 */
1518EAPI void evas_device_emulation_source_set(Evas_Device *dev, Evas_Device *src); 1518EAPI void evas_device_emulation_source_set(Evas_Device *dev, Evas_Device *src);
1519 1519
1520/** 1520/**
1521 * Get the emulation source device 1521 * Get the emulation source device
1522 * 1522 *
1523 * @param dev The device to query 1523 * @param dev The device to query
1524 * @return The source emulation device set by evas_device_emulation_source_set(). 1524 * @return The source emulation device set by evas_device_emulation_source_set().
1525 * 1525 *
1526 * @since 1.8 1526 * @since 1.8
1527 */ 1527 */
1528EAPI const Evas_Device *evas_device_emulation_source_get(const Evas_Device *dev); 1528EAPI const Evas_Device *evas_device_emulation_source_get(const Evas_Device *dev);
@@ -2101,7 +2101,7 @@ EAPI void evas_map_util_3d_rotate(Evas_Map *m, double dx, double dy,
2101 * Rotate the map in 3D using a unit quaternion. 2101 * Rotate the map in 3D using a unit quaternion.
2102 * 2102 *
2103 * This will rotate in 3D using a unit quaternion. Like with 2103 * This will rotate in 3D using a unit quaternion. Like with
2104 * evas_map_util_3d_rotate() you provide a center point 2104 * evas_map_util_3d_rotate() you provide a center point
2105 * to rotate around (in 3D). 2105 * to rotate around (in 3D).
2106 * 2106 *
2107 * @param m map to change. 2107 * @param m map to change.
@@ -5290,3 +5290,2152 @@ EAPI const Eina_List *evas_font_path_global_list(void) EINA_WARN_UNUSED_R
5290/** 5290/**
5291 * @} 5291 * @}
5292 */ 5292 */
5293
5294
5295 // 3D stuff
5296
5297 /**
5298 * @defgroup Evas_3D Evas 3D Extensions
5299 *
5300 * Evas extension to support 3D rendering.
5301 *
5302 * @ingroup Evas
5303 */
5304
5305/**
5306 * @page evas_3d_main Evas 3D
5307 *
5308 * @date 2014 (created)
5309 *
5310 * @section toc Table of Contents
5311 *
5312 * @li @ref evas_3d_intro
5313 * @li @ref evas_3d_example
5314 *
5315 * @section evas_3d_intro Introduction
5316 *
5317 * Evas 3D is an extension to support 3D scene graph rendering into 2D Evas
5318 * canvas supporting typicall tree-based scene graph manipulation and other 3D
5319 * graphics rendering techniques.
5320 *
5321 * Evas 3D provides 3D objects which are used for describing 3D scene and APIs
5322 * to connect the scene with an evas image object so that the scene is rendered
5323 * on that image object.
5324 *
5325 * Contruction of a 3D scene is process of locating desired cameras, lights and
5326 * meshes in the scene. Typically the scene is structured with some hierarchical
5327 * data structure. Evas 3D support n-ary tree structure for describing the
5328 * scene. Node is used to build the tree representation of the scene. Other
5329 * objects, like camera, light and mesh can be located in the scene by being
5330 * contained in a node.
5331 *
5332 * Like other 3D graphics engine, Evas 3D support standard 3D rendering method
5333 * like flat shading, phong shading and normal map and other features like
5334 * texture mapping, triangle meshes.
5335 *
5336 * Besides all the traditional 3D rendering things, one of the key feature of
5337 * the Evas 3D is that it is able to use existing evas objects as textures
5338 * inside of the 3D scene. "Existing evas objects" means all the EFL widgets
5339 * and applications. By supporting this, it is easy to make 3D version of an
5340 * application without modifying the original source that much.
5341 *
5342 * Also, 3D scene can be located on the canvas naturally stacked with existing
5343 * evas objects. This can make it possible putting 3D things into existing 2D
5344 * application layouts.
5345 *
5346 * @section evas_3d_example Introductory Example
5347 *
5348 * @include evas-3d-cube.c
5349 */
5350
5351/**
5352 * @defgroup Evas_3D_Types Types & Enums
5353 * @ingroup Evas_3D
5354 *
5355 * Primitive type definitions and enumations.
5356 */
5357
5358/**
5359 * @defgroup Evas_3D_Object Generic 3D Object Descriptions
5360 * @ingroup Evas_3D
5361 *
5362 * Evas 3D object is a generic type of all evas 3D objects like scene, node,
5363 * camera, light, mesh, texture and material. Evas 3D object is basically
5364 * reference counted. Any successful function call on an object which make a
5365 * reference to an another object will increase the reference count. When the
5366 * reference count gets to 0, the object will be actually deleted.
5367 *
5368 * Any modifications are automatically propagated to other objects referencing
5369 * the modified objects. As a result, if the scene object is set to modified
5370 * state, all image objects having the scene as a rendering source are marked
5371 * as dirty, so that rendering will be updated at next frame. But all these
5372 * things are done internally, so feel free to forget about calling some kind
5373 * of update functions.
5374 */
5375
5376/**
5377 * @defgroup Evas_3D_Scene Scene Object
5378 * @ingroup Evas_3D
5379 *
5380 * A scene represents a captured image of a scene graph through its viewing
5381 * camera. A scene can be set to an image object to be displayed on the Evas
5382 * canvas by using evas_object_image_3d_scene_set() function.
5383 */
5384
5385/**
5386 * @defgroup Evas_3D_Node Node Object
5387 * @ingroup Evas_3D
5388 *
5389 * A node is used for hierarchical construction of a scene graph. Evas 3D
5390 * provides n-ary tree structure for the scene graph construction.A node has
5391 * its position, orientation and scale. Other objects, like camera, light and
5392 * mesh can be contained in a node to be located in a 3D space.
5393 */
5394
5395/**
5396 * @defgroup Evas_3D_Camera Camera Object
5397 * @ingroup Evas_3D
5398 *
5399 * A camera object is used for taking a picture of a scene graph. A camera
5400 * object itself is just a set of properties on how the camera should take the
5401 * picture (like focus length and film size of the real world cameras). To be
5402 * able to take a shot of the scene, a camera should be located in the scene, so
5403 * that it has its viewing position and direction. It is done by containing the
5404 * camera on a node. If one wants to locate several cameras having same
5405 * properties, instead of creating multiple cameras, just create one camera and
5406 * multiple nodes containing the camera and locate them at each desired position
5407 * and direction. Just for convinience, use evas_3d_node_position_set() to move
5408 * the camera to desired position and use evas_3d_node_look_at_set() to adjust
5409 * the viewing direction of the camera.
5410 */
5411
5412/**
5413 * @defgroup Evas_3D_Light Light Object
5414 * @ingroup Evas_3D
5415 *
5416 * A light object represents a set of properties of a light source. Evas 3D
5417 * provides standard reflection model that of ambient, diffuse and specular
5418 * reflection model. Also, Evas 3D support 3 types of light model, directional,
5419 * point and spot light. Light position and direction is determined by the node
5420 * containing the light.
5421 */
5422
5423/**
5424 * @defgroup Evas_3D_Mesh Mesh Object
5425 * @ingroup Evas_3D
5426 *
5427 * A mesh object is a set of information on a visible geometrical object like
5428 * character model, terrain or other structures and entities. Evas 3D support
5429 * key-frame-based mesh animation, so a mesh can have multiple frames and each
5430 * frame has its own material and geometric data. Like other data objects, a
5431 * mesh can be located on a scene by being contained in a node. The mesh is
5432 * transformed from its modeling coordinate space into the node's coordinate
5433 * space. Also, the frame number is saved in the containing node. So, one can
5434 * locate multiple nodes having same mesh object with different animation frame
5435 * and transform. Unlike camera and light object, multiple meshes can be
5436 * contained in a single node.
5437 */
5438
5439/**
5440 * @defgroup Evas_3D_Texture Texture Object
5441 * @ingroup Evas_3D
5442 *
5443 * A texture object is an image represents material of surfaces. A texture can
5444 * be set to a slot of Evas_3D_Material by using evas_3d_material_texture_set()
5445 * function. The data of a texture can be loaded from memory, file and other
5446 * Evas_Object.
5447 */
5448
5449/**
5450 * @defgroup Evas_3D_Material Material Object
5451 * @ingroup Evas_3D
5452 *
5453 * A material object represents properties of surfaces. Evas 3D defines the
5454 * properties with 5 material attributes, ambient, diffuse, specular emission
5455 * and normal. Each attribute have its color value and texture map. Materials
5456 * are used to determine the color of mesh surfaces.
5457 */
5458
5459/**
5460 * @typedef Evas_Real
5461 *
5462 * Floating-point data type
5463 *
5464 * Evas 3D use its own floating-point type. Even though it's a standard IEEE
5465 * 754 floating-point type always use Evas_Real for the type safety. Double
5466 * precision and fixed-point types will be useful but it's not supported yet.
5467 *
5468 * @ingroup Evas_3D_Types
5469 */
5470typedef double Evas_Real;
5471
5472/**
5473 * @typedef Evas_3D_Scene
5474 *
5475 * Scene object handle
5476 *
5477 * @ingroup Evas_3D_Scene
5478 */
5479typedef Eo Evas_3D_Scene;
5480
5481/**
5482 * @typedef Evas_3D_Node
5483 *
5484 * Node object handle
5485 *
5486 * @ingroup Evas_3D_Node
5487 */
5488typedef Eo Evas_3D_Node;
5489
5490/**
5491 * @typedef Evas_3D_Camera
5492 *
5493 * Camera object handle
5494 *
5495 * @ingroup Evas_3D_Camera
5496 */
5497typedef Eo Evas_3D_Camera;
5498
5499/**
5500 * @typedef Evas_3D_Light
5501 *
5502 * Light object handle
5503 *
5504 * @ingroup Evas_3D_Light
5505 */
5506typedef Eo Evas_3D_Light;
5507
5508/**
5509 * @typedef Evas_3D_Mesh
5510 *
5511 * Mesh object handle
5512 *
5513 * @ingroup Evas_3D_Mesh
5514 */
5515typedef Eo Evas_3D_Mesh;
5516
5517/**
5518 * @typedef Evas_3D_Texture
5519 *
5520 * Texture object handle
5521 *
5522 * @ingroup Evas_3D_Texture
5523 */
5524typedef Eo Evas_3D_Texture;
5525
5526/**
5527 * @typedef Evas_3D_Material
5528 *
5529 * Material object handle
5530 *
5531 * @ingroup Evas_3D_Material
5532 */
5533typedef Eo Evas_3D_Material;
5534
5535/**
5536 * Transform space
5537 * @ingroup Evas_3D_Types
5538 */
5539typedef enum _Evas_3D_Space
5540{
5541 EVAS_3D_SPACE_LOCAL, /**< Local coordinate space */
5542 EVAS_3D_SPACE_PARENT, /**< Parent coordinate space */
5543 EVAS_3D_SPACE_WORLD, /**< World coordinate space */
5544} Evas_3D_Space;
5545
5546/**
5547 * Types of a node
5548 * @ingroup Evas_3D_Types
5549 */
5550typedef enum _Evas_3D_Node_Type
5551{
5552 EVAS_3D_NODE_TYPE_NODE, /**< Node with no items */
5553 EVAS_3D_NODE_TYPE_CAMERA, /**< Node which can contain camera object */
5554 EVAS_3D_NODE_TYPE_LIGHT, /**< Node which can contain light object */
5555 EVAS_3D_NODE_TYPE_MESH, /**< Node which can contain mesh objects */
5556} Evas_3D_Node_Type;
5557
5558/**
5559 * Vertex attribute IDs
5560 * @ingroup Evas_3D_Types
5561 */
5562typedef enum _Evas_3D_Vertex_Attrib
5563{
5564 EVAS_3D_VERTEX_POSITION, /**< Vertex position */
5565 EVAS_3D_VERTEX_NORMAL, /**< Vertex normal */
5566 EVAS_3D_VERTEX_TANGENT, /**< Vertex tangent (for normal mapping) */
5567 EVAS_3D_VERTEX_COLOR, /**< Vertex color */
5568 EVAS_3D_VERTEX_TEXCOORD, /**< Vertex texture coordinate */
5569} Evas_3D_Vertex_Attrib;
5570
5571/**
5572 * Index formats
5573 * @ingroup Evas_3D_Types
5574 */
5575typedef enum _Evas_3D_Index_Format
5576{
5577 EVAS_3D_INDEX_FORMAT_NONE, /**< Indexing is not used */
5578 EVAS_3D_INDEX_FORMAT_UNSIGNED_BYTE, /**< Index is of type unsigned byte */
5579 EVAS_3D_INDEX_FORMAT_UNSIGNED_SHORT, /**< Index is of type unsigned short */
5580} Evas_3D_Index_Format;
5581
5582/**
5583 * Vertex assembly modes
5584 * @ingroup Evas_3D_Types
5585 *
5586 * Vertex assembly represents how the vertices are organized into geometric
5587 * primitives.
5588 */
5589typedef enum _Evas_3D_Vertex_Assembly
5590{
5591 EVAS_3D_VERTEX_ASSEMBLY_POINTS, /**< A vertex is rendered as a point */
5592 EVAS_3D_VERTEX_ASSEMBLY_LINES, /**< Two vertices are organized as a line */
5593 EVAS_3D_VERTEX_ASSEMBLY_LINE_STRIP, /**< Vertices are organized as a connected line path */
5594 EVAS_3D_VERTEX_ASSEMBLY_LINE_LOOP, /**< Vertices are organized as a closed line path */
5595 EVAS_3D_VERTEX_ASSEMBLY_TRIANGLES, /**< Three vertices are organized as a triangle */
5596 EVAS_3D_VERTEX_ASSEMBLY_TRIANGLE_STRIP, /**< Vertices are organized as connected triangles */
5597 EVAS_3D_VERTEX_ASSEMBLY_TRIANGLE_FAN, /**< Vertices are organized as a triangle fan */
5598} Evas_3D_Vertex_Assembly;
5599
5600/**
5601 * Color formats of pixel data
5602 * @ingroup Evas_3D_Types
5603 */
5604typedef enum _Evas_3D_Color_Format
5605{
5606 EVAS_3D_COLOR_FORMAT_RGBA, /**< Color contains full components, red, green, blue and alpha */
5607 EVAS_3D_COLOR_FORMAT_RGB, /**< Color contains only red, green and blue components */
5608 EVAS_3D_COLOR_FORMAT_ALPHA, /**< Color contains only alpha component */
5609} Evas_3D_Color_Format;
5610
5611/**
5612 * Pixel formats
5613 * @ingroup Evas_3D_Types
5614 */
5615typedef enum _Evas_3D_Pixel_Format
5616{
5617 EVAS_3D_PIXEL_FORMAT_8, /**< 8-bit pixel with single component */
5618 EVAS_3D_PIXEL_FORMAT_565, /**< 16-bit pixel with three components (5-6-5 bit) */
5619 EVAS_3D_PIXEL_FORMAT_888, /**< 24-bit pixel with three 8-bit components */
5620 EVAS_3D_PIXEL_FORMAT_8888, /**< 32-bit pixel with four 8-bit components */
5621 EVAS_3D_PIXEL_FORMAT_4444, /**< 16-bit pixel with four 4-bit components */
5622 EVAS_3D_PIXEL_FORMAT_5551, /**< 16-bit pixel with four components (5-5-5-1 bit) */
5623} Evas_3D_Pixel_Format;
5624
5625/**
5626 * Wrap modes
5627 * @ingroup Evas_3D_Types
5628 */
5629typedef enum _Evas_3D_Wrap_Mode
5630{
5631 EVAS_3D_WRAP_MODE_CLAMP, /**< Values will be clamped to be in range [min, max] */
5632 EVAS_3D_WRAP_MODE_REPEAT, /**< Values will be repeated */
5633 EVAS_3D_WRAP_MODE_REFLECT, /**< Values will be repeated in a reflected manner */
5634} Evas_3D_Wrap_Mode;
5635
5636/**
5637 * Texture filters
5638 * @ingroup Evas_3D_Types
5639 */
5640typedef enum _Evas_3D_Texture_Filter
5641{
5642 EVAS_3D_TEXTURE_FILTER_NEAREST, /**< Samples nearest texel */
5643 EVAS_3D_TEXTURE_FILTER_LINEAR, /**< Lineary interpolate nearby texels */
5644 EVAS_3D_TEXTURE_FILTER_NEAREST_MIPMAP_NEAREST, /**< Nearest sampling mipmap */
5645 EVAS_3D_TEXTURE_FILTER_LINEAR_MIPMAP_NEAREST, /**< Nearest sampling mipmap and interpolate */
5646 EVAS_3D_TEXTURE_FILTER_NEAREST_MIPMAP_LINEAR, /**< Linear sampling in nearest mipmap */
5647 EVAS_3D_TEXTURE_FILTER_LINEAR_MIPMAP_LINEAR, /**< Linear sampling in mipmap and interpolate */
5648} Evas_3D_Texture_Filter;
5649
5650/**
5651 * Shade modes
5652 * @ingroup Evas_3D_Types
5653 */
5654typedef enum _Evas_3D_Shade_Mode
5655{
5656 EVAS_3D_SHADE_MODE_VERTEX_COLOR, /**< Shaded using vertex color attribute */
5657 EVAS_3D_SHADE_MODE_DIFFUSE, /**< Shaded using material diffuse term */
5658 EVAS_3D_SHADE_MODE_FLAT, /**< Per-vertex flat lighting */
5659 EVAS_3D_SHADE_MODE_PHONG, /**< Per-pixel phong shading */
5660 EVAS_3D_SHADE_MODE_NORMAL_MAP, /**< Per-pixel normal map shading */
5661} Evas_3D_Shade_Mode;
5662
5663/**
5664 * Material attributes
5665 * @ingroup Evas_3D_Types
5666 */
5667typedef enum _Evas_3D_Material_Attrib
5668{
5669 EVAS_3D_MATERIAL_AMBIENT, /**< Ambient term */
5670 EVAS_3D_MATERIAL_DIFFUSE, /**< Diffuse term */
5671 EVAS_3D_MATERIAL_SPECULAR, /**< Specular term */
5672 EVAS_3D_MATERIAL_EMISSION, /**< Emission term */
5673 EVAS_3D_MATERIAL_NORMAL, /**< Normal map term */
5674} Evas_3D_Material_Attrib;
5675
5676/**
5677 * Mesh file type
5678 * @ingroup Evas_3D_Types
5679 */
5680typedef enum _Evas_3D_Mesh_File_Type
5681{
5682 EVAS_3D_MESH_FILE_TYPE_MD2, /**< Quake's MD2 mesh file format */
5683} Evas_3D_Mesh_File_Type;
5684
5685typedef enum _Evas_3D_Pick_Type
5686{
5687 EVAS_3D_PICK_NODE,
5688 EVAS_3D_PICK_MESH,
5689} Evas_3D_Pick_Type;
5690
5691/**
5692 * Set the scene on an image object.
5693 *
5694 * @param obj Image object.
5695 * @param scene Scene object used as a content of the given image object.
5696 *
5697 * An image object can get its content from various sources like memory buffers,
5698 * image files and other evas object. A scene also can be a source for an image
5699 * object to display the rendered result onto evas canvas.
5700 *
5701 * Any existing content (data, file or proxy source) will be removed after this
5702 * call. Setting @p src to @c NULL detach the 3D scene from the image object.
5703 *
5704 * @ingroup Evas_3D_Scene
5705 */
5706EAPI void evas_object_image_t3d_scene_set(Evas_Object *obj, Evas_3D_Scene *scene) EINA_ARG_NONNULL(1);
5707
5708/**
5709 * Get the current scene of an image object.
5710 *
5711 * @param obj Image object.
5712 * @return Scene object handle (if any), or @c NULL if there's no scene attached.
5713 *
5714 * @ingroup Evas_3D_Scene
5715 */
5716EAPI Evas_3D_Scene *evas_object_image_t3d_scene_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5717
5718/**
5719 * Create a new scene on the given Evas @p e canvas.
5720 *
5721 * @param e The given canvas.
5722 * @return The created scene handle.
5723 *
5724 * @ingroup Evas_3D_Scene
5725 */
5726EAPI Evas_3D_Scene *evas_3d_scene_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5727
5728/**
5729 * Delete a scene from its belonging Evas canvas.
5730 *
5731 * @param scene The given scene to be deleted.
5732 *
5733 * @ingroup Evas_3D_Scene
5734 */
5735EAPI void evas_3d_scene_del(Evas_3D_Scene *scene) EINA_ARG_NONNULL(1);
5736
5737/**
5738 * Get the Evas canvas where the given scene belongs to.
5739 *
5740 * @param scene The given scene.
5741 * @return The Evas canvas.
5742 *
5743 * @ingroup Evas_3D_Scene
5744 */
5745EAPI Evas *evas_3d_scene_evas_get(const Evas_3D_Scene *scene) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5746
5747/**
5748 * Set the root node of a scene.
5749 *
5750 * @param scene The given scene.
5751 * @param node A node which will be used as a root node for the scene.
5752 *
5753 * @ingroup Evas_3D_Scene
5754 */
5755EAPI void evas_3d_scene_root_node_set(Evas_3D_Scene *scene, Evas_3D_Node *node) EINA_ARG_NONNULL(1);
5756
5757/**
5758 * Get the root node of a scene.
5759 *
5760 * @param scene The given scene.
5761 * @return The root node of the given scene.
5762 *
5763 * @ingroup Evas_3D_Scene
5764 */
5765EAPI Evas_3D_Node *evas_3d_scene_root_node_get(const Evas_3D_Scene *scene) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5766
5767/**
5768 * Set the camera node of a scene.
5769 *
5770 * @param scene The given scene.
5771 * @param node A node which will be used as a camera node for the scene.
5772 *
5773 * @ingroup Evas_3D_Scene
5774 */
5775EAPI void evas_3d_scene_camera_node_set(Evas_3D_Scene *scene, Evas_3D_Node *node) EINA_ARG_NONNULL(1);
5776
5777/**
5778 * Get the camera node of a scene.
5779 *
5780 * @param scene The given scene.
5781 * @return The camera node of the given scene.
5782 *
5783 * @ingroup Evas_3D_Scene
5784 */
5785EAPI Evas_3D_Node *evas_3d_scene_camera_node_get(const Evas_3D_Scene *scene) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5786
5787/**
5788 * Set the resolution of a scene.
5789 *
5790 * @param scene The given scene.
5791 * @param w Width of the resolution.
5792 * @param h Height of the resolution.
5793 *
5794 * A scene should be rendered to be displayed through an image objects. The
5795 * resolution defines size of the internal surface holding the rendered result.
5796 *
5797 * @ingroup Evas_3D_Scene
5798 */
5799EAPI void evas_3d_scene_size_set(Evas_3D_Scene *scene, int w, int h) EINA_ARG_NONNULL(1);
5800
5801/**
5802 * Get the internal resolution of a scene.
5803 *
5804 * @param scene The given scene.
5805 * @param w Pointer to receive width of the resolution.
5806 * @param h Pointer to receive height of the resolution.
5807 *
5808 * @ingroup Evas_3D_Scene
5809 */
5810EAPI void evas_3d_scene_size_get(const Evas_3D_Scene *scene, int *w, int *h) EINA_ARG_NONNULL(1);
5811
5812/**
5813 * Set the background color of a scene.
5814 *
5815 * @param scene The given scene.
5816 * @param r Red component of the background color.
5817 * @param g Green component of the background color.
5818 * @param b Blue component of the background color.
5819 * @param a Alpha component of the background color.
5820 *
5821 * Background color defines initial color of pixels before a scene is rendered.
5822 * If you want to display a scene with background evas objects are still
5823 * remaining as if it was the background, set the alpha term to 0.0.
5824 *
5825 * Default background color is (0.0, 0.0, 0.0, 0.0).
5826 *
5827 * @ingroup Evas_3D_Scene
5828 */
5829EAPI void evas_3d_scene_background_color_set(Evas_3D_Scene *scene, Evas_Real r, Evas_Real g, Evas_Real b, Evas_Real a) EINA_ARG_NONNULL(1);
5830
5831/**
5832 * Get the background color of a scene.
5833 *
5834 * @param scene The given scene.
5835 * @param r Pointer to receive red component of the background color.
5836 * @param g Pointer to receive green component of the background color.
5837 * @param b Pointer to receive blue component of the background color.
5838 * @param a Pointer to receive alpha component of the background color.
5839 *
5840 * @ingroup Evas_3D_Scene
5841 */
5842EAPI void evas_3d_scene_background_color_get(const Evas_3D_Scene *scene, Evas_Real *r, Evas_Real *g, Evas_Real *b, Evas_Real *a) EINA_ARG_NONNULL(1);
5843
5844/**
5845 * Get information on the most front visible mesh for the given position.
5846 *
5847 * @param scene The given scene.
5848 * @param x X coordinate of the picking position.
5849 * @param y Y coordinate of the picking position.
5850 * @param node Pointer to receive the node contains the picked mesh.
5851 * @param mesh Pointer to receive the picked mesh.
5852 * @param s Pointer to receive the texture "s" coordinate.
5853 * @param t Pointer to receive the texture "t" coordinate.
5854 *
5855 * (x, y) is the screen coordinate of the given scene. That is, left-top is
5856 * (0, 0) and right-bottom is (w, h) where (w, h) is the size of the scene.
5857 * The texture coordinate is useful when using proxy texture source.
5858 *
5859 * @ingroup Evas_3D_Scene
5860 */
5861EAPI Eina_Bool evas_3d_scene_pick(const Evas_3D_Scene *scene, Evas_Real x, Evas_Real y, Evas_3D_Node **node, Evas_3D_Mesh **mesh, Evas_Real *s, Evas_Real *t) EINA_ARG_NONNULL(1);
5862
5863/**
5864 * Create a new node on the given Evas @p canvas.
5865 *
5866 * @param e The given canvas.
5867 * @param type The type of the node.
5868 * @return The created node handle.
5869 *
5870 * @ingroup Evas_3D_Node
5871 */
5872EAPI Evas_3D_Node *evas_3d_node_add(Evas *e, Evas_3D_Node_Type type) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5873
5874/**
5875 * Delete a node from its belonging Evas canvas.
5876 *
5877 * @param node The given node.
5878 *
5879 * @see evas_3d_node_add()
5880 *
5881 * @ingroup Evas_3D_Node
5882 */
5883EAPI void evas_3d_node_del(Evas_3D_Node *node) EINA_ARG_NONNULL(1);
5884
5885/**
5886 * Get the type of the given node.
5887 *
5888 * @param node The given node.
5889 * @return The type of the given node.
5890 *
5891 * @see evas_3d_node_add()
5892 *
5893 * @ingroup Evas_3D_Node
5894 */
5895EAPI Evas_3D_Node_Type evas_3d_node_type_get(const Evas_3D_Node *node) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5896
5897/**
5898 * Get the Evas canvas where the given node belongs to.
5899 *
5900 * @param node The given node.
5901 * @return The Evas canvas.
5902 *
5903 * @see evas_3d_node_add()
5904 *
5905 * @ingroup Evas_3D_Node
5906 */
5907EAPI Evas *evas_3d_node_evas_get(const Evas_3D_Node *node) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5908
5909/**
5910 * Add a member node to the given node.
5911 *
5912 * @param node The given node which will be the parent.
5913 * @param member Node object to be added.
5914 *
5915 * Nodes can be constructed into N-ary tree structure like other ordinary scene
5916 * graph. Basically a node inherit transforms from its parent.
5917 *
5918 * @see evas_3d_node_parent_get()
5919 *
5920 * @ingroup Evas_3D_Node
5921 */
5922EAPI void evas_3d_node_member_add(Evas_3D_Node *node, Evas_3D_Node *member) EINA_ARG_NONNULL(1, 2);
5923
5924/**
5925 * Delete a member node from the given node.
5926 *
5927 * @param node The given node.
5928 * @param member Member node to be deleted from the given node.
5929 *
5930 * @see evas_3d_node_member_add()
5931 *
5932 * @ingroup Evas_3D_Node
5933 */
5934EAPI void evas_3d_node_member_del(Evas_3D_Node *node, Evas_3D_Node *member) EINA_ARG_NONNULL(1, 2);
5935
5936/**
5937 * Get the parent node of the given node.
5938 *
5939 * @param node The given node.
5940 * @return The parent node of the given node.
5941 *
5942 * @see evas_3d_node_member_add()
5943 *
5944 * @ingroup Evas_3D_Node
5945 */
5946EAPI Evas_3D_Node *evas_3d_node_parent_get(const Evas_3D_Node *node) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5947
5948/**
5949 * Get the list of member nodes of the given node.
5950 *
5951 * @param node The given node.
5952 * @return The list of member nodes if any or @c NULL if there are none.
5953 *
5954 * @see evas_3d_node_member_add()
5955 *
5956 * @ingroup Evas_3D_Node
5957 */
5958EAPI const Eina_List *evas_3d_node_member_list_get(const Evas_3D_Node *node) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
5959
5960/**
5961 * @defgroup Evas_3D_Node_Transform
5962 * @ingroup Evas_3D_Node
5963 *
5964 * Functions that manipulate node transforms.
5965 *
5966 * Evas_3D_Node does not provide standard 4x4 matrix to transform something.
5967 * Instead, one can set position, orientation and scale of a node separately.
5968 * A node will be first scaled and rotated and then translated according to its
5969 * position, orientation and scale. Each transform attributes can be set to
5970 * inherit from its parent or not.
5971 */
5972
5973/**
5974 * Set the position of the given node.
5975 *
5976 * @param node The given node.
5977 * @param x X coordinate of the position.
5978 * @param y Y coordinate of the position.
5979 * @param z Z coordinate of the position.
5980 *
5981 * According to the inheritance flag, (x, y, z) can be a world space position or
5982 * parent space position.
5983 *
5984 * Default position is (0.0, 0.0, 0.0).
5985 *
5986 * @see evas_3d_node_position_inherit_set()
5987 *
5988 * @ingroup Evas_3D_Node_Transform
5989 */
5990EAPI void evas_3d_node_position_set(Evas_3D_Node *node, Evas_Real x, Evas_Real y, Evas_Real z) EINA_ARG_NONNULL(1);
5991
5992/**
5993 * Set the orientation of the given node using quaternion.
5994 *
5995 * @param node The given node.
5996 * @param x X term of the orientation quaternion (w, x, y, z)
5997 * @param y Y term of the orientation quaternion (w, x, y, z)
5998 * @param z Z term of the orientation quaternion (w, x, y, z)
5999 * @param w W term of the orientation quaternion (w, x, y, z)
6000 *
6001 * According the the inheritance flag, (w, x, y, z) can be a world space
6002 * orientation or parent space orientation.
6003 *
6004 * Default orientation is (1.0, 0.0, 0.0, 0.0) (identity quaternion).
6005 *
6006 * @see evas_3d_node_orientation_inherit_set()
6007 *
6008 * @ingroup Evas_3D_Node_Transform
6009 */
6010EAPI void evas_3d_node_orientation_set(Evas_3D_Node *node, Evas_Real x, Evas_Real y, Evas_Real z, Evas_Real w) EINA_ARG_NONNULL(1);
6011
6012/**
6013 * Set the orientation of the given node using euler angle.
6014 *
6015 * @param node The given node.
6016 * @param x Rotation angle about X-axis.
6017 * @param y Rotation angle about Y-axis.
6018 * @param z Rotation angle about Z-axis.
6019 *
6020 * @see evas_3d_node_orientation_set()
6021 *
6022 * @ingroup Evas_3D_Node_Transform
6023 */
6024EAPI void evas_3d_node_orientation_euler_set(Evas_3D_Node *node, Evas_Real x, Evas_Real y, Evas_Real z) EINA_ARG_NONNULL(1);
6025
6026/**
6027 * Set the orientation of the given node using axis-angle.
6028 *
6029 * @param node The given node.
6030 * @param angle Rotation angle.
6031 * @param x X term of the rotation axis.
6032 * @param y Y term of the rotation axis.
6033 * @param z Z term of the rotation axis.
6034 *
6035 * @see evas_3d_node_orientation_set()
6036 *
6037 * @ingroup Evas_3D_Node_Transform
6038 */
6039EAPI void evas_3d_node_orientation_angle_axis_set(Evas_3D_Node *node, Evas_Real angle, Evas_Real x, Evas_Real y, Evas_Real z) EINA_ARG_NONNULL(1);
6040
6041/**
6042 * Set the scale of the given node.
6043 *
6044 * @param node The given node.
6045 * @param x Scale factor along X-axis.
6046 * @param y Scale factor along Y-axis.
6047 * @param z Scale factor along Z-axis.
6048 *
6049 * According to the inheritance flag, (x, y, z) can be a world space scale or
6050 * parent space scale. Be careful when using non-uniform scale factor with
6051 * inheritance, each transform attributes are not affected by other attributes.
6052 *
6053 * Default scale is (1.0, 1.0, 1.0).
6054 *
6055 * @see evas_3d_node_scale_inherit_set()
6056 *
6057 * @ingroup Evas_3D_Node_Transform
6058 */
6059EAPI void evas_3d_node_scale_set(Evas_3D_Node *node, Evas_Real x, Evas_Real y, Evas_Real z) EINA_ARG_NONNULL(1);
6060
6061/**
6062 * Get the position of the given node.
6063 *
6064 * @param node The given node.
6065 * @param x Pointer to receive X coordinate of the position.
6066 * @param y Pointer to receive Y coordinate of the position.
6067 * @param z Pointer to receive Z coordinate of the position.
6068 *
6069 * @see evas_3d_node_position_set()
6070 *
6071 * @ingroup Evas_3D_Node_Transform
6072 */
6073EAPI void evas_3d_node_position_get(const Evas_3D_Node *node, Evas_3D_Space space, Evas_Real *x, Evas_Real *y, Evas_Real *z) EINA_ARG_NONNULL(1);
6074
6075/**
6076 * Get the orientation of the given node as quaternion.
6077 *
6078 * @param node The given node.
6079 * @param x Pointer to receive X term of the orientation quaternion.
6080 * @param y Pointer to receive Y term of the orientation quaternion.
6081 * @param z Pointer to receive Z term of the orientation quaternion.
6082 * @param w Pointer to receive W term of the orientation quaternion.
6083 *
6084 * @see evas_3d_node_orientation_set()
6085 *
6086 * @ingroup Evas_3D_Node_Transform
6087 */
6088EAPI void evas_3d_node_orientation_get(const Evas_3D_Node *node, Evas_3D_Space space, Evas_Real *x, Evas_Real *y, Evas_Real *z, Evas_Real *w) EINA_ARG_NONNULL(1);
6089EAPI void evas_3d_node_scale_get(const Evas_3D_Node *node, Evas_3D_Space space, Evas_Real *x, Evas_Real *y, Evas_Real *z) EINA_ARG_NONNULL(1);
6090
6091/**
6092 * Set the position inheritance flag of the given node.
6093 *
6094 * @param node The given node.
6095 * @param inherit Whether to inherit parent position @c EINA_TRUE or not @c EINA_FALSE.
6096 *
6097 * When inheritance is enabled, a node's world space position is determined by
6098 * adding the parent node's world position and the node's position, otherwise,
6099 * the node's position will be the world space position.
6100 *
6101 * @ingroup Evas_3D_Node_Transform
6102 */
6103EAPI void evas_3d_node_position_inherit_set(Evas_3D_Node *node, Eina_Bool inherit) EINA_ARG_NONNULL(1);
6104
6105/**
6106 * Set the orientation inheritance flag of the given node.
6107 *
6108 * @param node The given node.
6109 * @param inherit Whether to inherit parent orientation @c EINA_TRUE or not @c EINA_FALSE.
6110 *
6111 * When inheritance is enabled, a node's world space orientation is determined
6112 * by multiplying the parent node's world orientation and the node's
6113 * orientation, otherwise, the node's orientation will be the world space
6114 * orientation.
6115 *
6116 * @ingroup Evas_3D_Node_Transform
6117 */
6118EAPI void evas_3d_node_orientation_inherit_set(Evas_3D_Node *node, Eina_Bool inherit) EINA_ARG_NONNULL(1);
6119
6120/**
6121 * Set the scale inheritance flag of the given node.
6122 *
6123 * @param node The given node.
6124 * @param inherit Whether to inherit parent scale @c EINA_TRUE or not @c EINA_FALSE.
6125 *
6126 * When inheritance is enabled, a node's world space scale is determined by
6127 * multiplying the parent node's world scale and the node's scale, otherwise,
6128 * the node's scale will be the world space scale.
6129 *
6130 * @ingroup Evas_3D_Node_Transform
6131 */
6132EAPI void evas_3d_node_scale_inherit_set(Evas_3D_Node *node, Eina_Bool inherit) EINA_ARG_NONNULL(1);
6133
6134/**
6135 * Get the position inheritance flag of the given node.
6136 *
6137 * @param node The given node.
6138 * @return @c EINA_TRUE if inheritance is enabled, or @c EINA_FALSE if not.
6139 *
6140 * @see evas_3d_node_position_inherit_set()
6141 *
6142 * @ingroup Evas_3D_Node_Transform
6143 */
6144EAPI Eina_Bool evas_3d_node_position_inherit_get(const Evas_3D_Node *node) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6145
6146/**
6147 * Get the orientation inheritance flag of the given node.
6148 *
6149 * @param node The given node.
6150 * @return @c EINA_TRUE if inheritance is enabled, or @c EINA_FALSE if not.
6151 *
6152 * @see evas_3d_node_orientation_inherit_set()
6153 *
6154 * @ingroup Evas_3D_Node_Transform
6155 */
6156EAPI Eina_Bool evas_3d_node_orientation_inherit_get(const Evas_3D_Node *node) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6157
6158/**
6159 * Get the scale inheritance flag of the given node.
6160 *
6161 * @param node The given node.
6162 * @return @c EINA_TRUE if inheritance is enabled, or @c EINA_FALSE if not.
6163 *
6164 * @see evas_3d_node_scale_inherit_set()
6165 *
6166 * @ingroup Evas_3D_Node_Transform
6167 */
6168EAPI Eina_Bool evas_3d_node_scale_inherit_get(const Evas_3D_Node *node) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6169
6170/**
6171 * Rotate the given node to look at desired position.
6172 *
6173 * @param node The given node.
6174 * @param target_space Space where the target position belongs to.
6175 * @param x X coordinate of the target position.
6176 * @param y Y coordinate of the target position.
6177 * @param z Z coordinate of the target position.
6178 * @param up_space Space where the up vector belongs to.
6179 * @param ux X term of the up vector.
6180 * @param uy Y term of the up vector.
6181 * @param uz Z term of the up vector.
6182 *
6183 * This function rotate the given node so that its forward vector (negative
6184 * Z-axis) points to the desired position and the up vector coincide with the
6185 * given up vector.
6186 *
6187 * @see evas_3d_node_orientation_set()
6188 *
6189 * @ingroup Evas_3D_Node_Transform
6190 */
6191EAPI void evas_3d_node_look_at_set(Evas_3D_Node *node, Evas_3D_Space target_space, Evas_Real x, Evas_Real y, Evas_Real z, Evas_3D_Space up_space, Evas_Real ux, Evas_Real uy, Evas_Real uz) EINA_ARG_NONNULL(1);
6192
6193/**
6194 * Set a camera to the given node.
6195 *
6196 * @param node The given node.
6197 * @param camera The camera to be set.
6198 *
6199 * If the node is not of type EVAS_3D_NODE_TYPE_CAMERA, error message will be
6200 * generated and nothing happens.
6201 *
6202 * @see evas_3d_node_add()
6203 *
6204 * @ingroup Evas_3D_Node
6205 */
6206EAPI void evas_3d_node_camera_set(Evas_3D_Node *node, Evas_3D_Camera *camera) EINA_ARG_NONNULL(1);
6207
6208/**
6209 * Get the camera of the given node.
6210 *
6211 * @param node The given node.
6212 * @return The camera of the given node if any, or @c NULL if there're none.
6213 *
6214 * @see evas_3d_node_camera_set()
6215 *
6216 * @ingroup Evas_3D_Node
6217 */
6218EAPI Evas_3D_Camera *evas_3d_node_camera_get(const Evas_3D_Node *node) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6219
6220/**
6221 * Set the light of the given node.
6222 *
6223 * @param node The given node.
6224 * @param light The light to be set.
6225 *
6226 * If the node is not of type EVAS_3D_NODE_TYPE_LIGHT, error message will be
6227 * generated and nothing happens.
6228 *
6229 * @see evas_3d_node_add()
6230 *
6231 * @ingroup Evas_3D_Node
6232 */
6233EAPI void evas_3d_node_light_set(Evas_3D_Node *node, Evas_3D_Light *light) EINA_ARG_NONNULL(1);
6234
6235/**
6236 * Get the light of the given node.
6237 *
6238 * @param node The given node.
6239 * @return The light of the given node if any, or @c NULL if there're none.
6240 *
6241 * @see evas_3d_node_light_set()
6242 *
6243 * @ingroup Evas_3D_Node
6244 */
6245EAPI Evas_3D_Light *evas_3d_node_light_get(const Evas_3D_Node *node) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6246
6247/**
6248 * Add a mesh to the given node.
6249 *
6250 * @param node The given node.
6251 * @param mesh The mesh to be added.
6252 *
6253 * If the node is not of type EVAS_3D_NODE_TYPE_MESH, error message will be
6254 * generated and nothing happens.
6255 *
6256 * @see evas_3d_node_add()
6257 *
6258 * @ingroup Evas_3D_Node
6259 */
6260EAPI void evas_3d_node_mesh_add(Evas_3D_Node *node, Evas_3D_Mesh *mesh) EINA_ARG_NONNULL(1);
6261
6262/**
6263 * Delete a mesh from the given node.
6264 *
6265 * @param node The given node.
6266 * @param mesh The mesh to be deleted.
6267 *
6268 * If the node is not of type EVAS_3D_NODE_TYPE_MESH or the given mesh does not
6269 * belong to the given node, error message will be gnerated and nothing happens.
6270 *
6271 * @see evas_3d_node_mesh_add()
6272 *
6273 * @ingroup Evas_3D_Node
6274 */
6275EAPI void evas_3d_node_mesh_del(Evas_3D_Node *node, Evas_3D_Mesh *mesh) EINA_ARG_NONNULL(1);
6276
6277/**
6278 * Get the list of meshes of the given node.
6279 *
6280 * @param node The given node.
6281 * @return The list of meshes if any, or @c NULL if there're none.
6282 *
6283 * If the node is not of type EVAS_3D_NODE_TYPE_MESH, error message will be
6284 * generated and @c NULL will be returned. If there're no meshes in the given
6285 * node, @c NULL will be returned.
6286 *
6287 * @see evas_3d_node_mesh_add()
6288 *
6289 * @ingroup Evas_3D_Node
6290 */
6291EAPI const Eina_List *evas_3d_node_mesh_list_get(const Evas_3D_Node *node) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6292
6293/**
6294 * Set the animation frame number of the given node for the given mesh.
6295 *
6296 * @param node The given node.
6297 * @param mesh The given mesh.
6298 * @param frame The animation frame number.
6299 *
6300 * If the node is not of type EVAS_3D_NODE_TYPE_MESH or the given mesh does not
6301 * belong to the given mesh error mesh will be generated and nothing happens.
6302 *
6303 * Default mesh frame is 0.
6304 *
6305 * @see evas_3d_node_mesh_add()
6306 *
6307 * @ingroup Evas_3D_Node
6308 */
6309EAPI void evas_3d_node_mesh_frame_set(Evas_3D_Node *node, Evas_3D_Mesh *mesh, int frame) EINA_ARG_NONNULL(1);
6310
6311/**
6312 * Set the animation frame number of the given node for the given mesh.
6313 *
6314 * @param node The given node.
6315 * @param mesh The given mesh.
6316 * @param frame The animation frame number.
6317 *
6318 * If the node is not of type EVAS_3D_NODE_TYPE_MESH or the given mesh does not
6319 * belong to the given mesh error mesh will be generated and nothing happens.
6320 *
6321 * @see evas_3d_node_mesh_add()
6322 *
6323 * @ingroup Evas_3D_Node
6324 */
6325EAPI int evas_3d_node_mesh_frame_get(const Evas_3D_Node *node, Evas_3D_Mesh *mesh) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6326
6327/**
6328 * Create a new camera on the given Evas @p canvas.
6329 *
6330 * @param e The given canvas.
6331 * @return The created camera handle.
6332 *
6333 * @ingroup Evas_3D_Camera
6334 */
6335EAPI Evas_3D_Camera *evas_3d_camera_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6336
6337/**
6338 * Delete a node from its belonging Evas canvas.
6339 *
6340 * @param camera The given camera.
6341 *
6342 * @see evas_3d_camera_add()
6343 *
6344 * @ingroup Evas_3D_Camera
6345 */
6346EAPI void evas_3d_camera_del(Evas_3D_Camera *camera) EINA_ARG_NONNULL(1);
6347
6348/**
6349 * Get the Evas canvas where the given node belongs to.
6350 *
6351 * @param camera The given camera.
6352 * @return The Evas canvas.
6353 *
6354 * @see evas_3d_node_add()
6355 *
6356 * @ingroup Evas_3D_Camera
6357 */
6358EAPI Evas *evas_3d_camera_evas_get(const Evas_3D_Camera *camera) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6359
6360/**
6361 * Set the projection matrix of the given camera.
6362 *
6363 * @param camera The given camera.
6364 * @param matrix Pointer to the array of 16 Evas_Real values in column major order.
6365 *
6366 * Default projection matrix is identity matrix.
6367 *
6368 * @see evas_3d_camera_projection_perspective_set()
6369 * @see evas_3d_camera_projection_ortho_set()
6370 * @see evas_3d_camera_projection_frustum_set()
6371 *
6372 * @ingroup Evas_3D_Camera
6373 */
6374EAPI void evas_3d_camera_projection_matrix_set(Evas_3D_Camera *camera, const Evas_Real *matrix) EINA_ARG_NONNULL(1);
6375
6376/**
6377 * Get the projection matrix of the given camera.
6378 *
6379 * @param camera The given camera.
6380 * @param matrix Pointer to receive the 16 Evas_Real values in column major order.
6381 *
6382 * @see evas_3d_camera_projection_matrix_set()
6383 *
6384 * @ingroup Evas_3D_Camera
6385 */
6386EAPI void evas_3d_camera_projection_matrix_get(const Evas_3D_Camera *camera, Evas_Real *matrix) EINA_ARG_NONNULL(1, 2);
6387
6388/**
6389 * Set the projection matrix of the given camera with perspective projection.
6390 *
6391 * @param camera The given camera.
6392 * @param fovy Field of view angle in Y direction.
6393 * @param aspect Aspect ratio.
6394 * @param near Distance to near clipping plane.
6395 * @param far Distance to far clipping plane.
6396 *
6397 * @see evas_3d_camera_projection_matrix_set()
6398 *
6399 * @ingroup Evas_3D_Camera
6400 */
6401EAPI void evas_3d_camera_projection_perspective_set(Evas_3D_Camera *camera, Evas_Real fovy, Evas_Real aspect, Evas_Real near, Evas_Real far) EINA_ARG_NONNULL(1);
6402
6403/**
6404 * Set the projection matrix of the given camera with frustum projection.
6405 *
6406 * @param camera The given camera.
6407 * @param left Left X coordinate of the near clipping plane.
6408 * @param right Right X coordinate of the near clipping plane.
6409 * @param top Top Y coordinate of the near clipping plane.
6410 * @param bottom Bottom Y coordinate of the near clipping plane.
6411 * @param near Distance to near clipping plane.
6412 * @param far Distance to far clipping plane.
6413 *
6414 * @see evas_3d_camera_projection_matrix_set()
6415 *
6416 * @ingroup Evas_3D_Camera
6417 */
6418EAPI void evas_3d_camera_projection_frustum_set(Evas_3D_Camera *camera, Evas_Real left, Evas_Real right, Evas_Real bottom, Evas_Real top, Evas_Real near, Evas_Real far) EINA_ARG_NONNULL(1);
6419
6420/**
6421 * Set the projection matrix of the given camera with orthogonal projection.
6422 *
6423 * @param camera The given camera.
6424 * @param left Left X coordinate of the near clipping plane.
6425 * @param right Right X coordinate of the near clipping plane.
6426 * @param top Top Y coordinate of the near clipping plane.
6427 * @param bottom Bottom Y coordinate of the near clipping plane.
6428 * @param near Distance to near clipping plane.
6429 * @param far Distance to far clipping plane.
6430 *
6431 * @see evas_3d_camera_projection_matrix_set()
6432 *
6433 * @ingroup Evas_3D_Camera
6434 */
6435EAPI void evas_3d_camera_projection_ortho_set(Evas_3D_Camera *camera, Evas_Real left, Evas_Real right, Evas_Real bottom, Evas_Real top, Evas_Real near, Evas_Real far) EINA_ARG_NONNULL(1);
6436
6437/**
6438 * Create a new light on the given Evas @p canvas.
6439 *
6440 * @param e The given canvas.
6441 * @return The created light handle.
6442 *
6443 * @ingroup Evas_3D_Light
6444 */
6445EAPI Evas_3D_Light *evas_3d_light_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6446
6447/**
6448 * Delete a node from its belonging Evas canvas.
6449 *
6450 * @param light The given light.
6451 *
6452 * @see evas_3d_light_add()
6453 *
6454 * @ingroup Evas_3D_Light
6455 */
6456EAPI void evas_3d_light_del(Evas_3D_Light *light) EINA_ARG_NONNULL(1);
6457
6458/**
6459 * Get the Evas canvas where the given node belongs to.
6460 *
6461 * @param light The given light.
6462 * @return The Evas canvas.
6463 *
6464 * @see evas_3d_node_add()
6465 *
6466 * @ingroup Evas_3D_Light
6467 */
6468EAPI Evas *evas_3d_light_evas_get(const Evas_3D_Light *light) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6469
6470/**
6471 * Set the directional flag of the given light.
6472 *
6473 * @param light The given light.
6474 * @param directional Whether the light is directional (@c EINA_TRUE), or not (@c EINA_FALSE).
6475 *
6476 * Directional light is a type of light which is infinitely far away with no
6477 * attenuation. The light direction is determined by the containing node's
6478 * forward vector (negative Z-axis).
6479 *
6480 * By default, directional is not enabled.
6481 *
6482 * @see evas_3d_node_look_at_set()
6483 *
6484 * @ingroup Evas_3D_Light
6485 */
6486EAPI void evas_3d_light_directional_set(Evas_3D_Light *light, Eina_Bool directional) EINA_ARG_NONNULL(1);
6487
6488/**
6489 * Get the directional flag of the given light.
6490 *
6491 * @param light The given light.
6492 * @return @c EINA_TRUE if the light is directional or @c EINA_FALSE if not.
6493 *
6494 * @see evas_3d_light_directional_set()
6495 *
6496 * @ingroup Evas_3D_Light
6497 */
6498EAPI Eina_Bool evas_3d_light_directional_get(const Evas_3D_Light *light) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6499
6500/**
6501 * Set the ambient color of the given light.
6502 *
6503 * @param light The given light.
6504 * @param r Red component of the ambient color between [0.0, 1.0].
6505 * @param g Green component of the ambient color between [0.0, 1.0].
6506 * @param b Blue component of the ambient color between [0.0, 1.0].
6507 * @param a Alpha component of the ambient color between [0.0, 1.0].
6508 *
6509 * Default ambient color is (0.0, 0.0, 0.0, 1.0).
6510 *
6511 * @ingroup Evas_3D_Light
6512 */
6513EAPI void evas_3d_light_ambient_set(Evas_3D_Light *light, Evas_Real r, Evas_Real g, Evas_Real b, Evas_Real a) EINA_ARG_NONNULL(1);
6514
6515/**
6516 * Get the ambient color of the given light.
6517 *
6518 * @param light The given light.
6519 * @param r Pointer to receive the red component of the ambient color.
6520 * @param g Pointer to receive the green component of the ambient color.
6521 * @param b Pointer to receive the blue component of the ambient color.
6522 * @param a Pointer to receive the alpha component of the ambient color.
6523 *
6524 * @see evas_3d_light_ambient_set()
6525 *
6526 * @ingroup Evas_3D_Light
6527 */
6528EAPI void evas_3d_light_ambient_get(const Evas_3D_Light *light, Evas_Real *r, Evas_Real *g, Evas_Real *b, Evas_Real *a) EINA_ARG_NONNULL(1);
6529
6530/**
6531 * Set the diffuse color of the given light.
6532 *
6533 * @param light The given light.
6534 * @param r Red component of the diffuse color between [0.0, 1.0].
6535 * @param g Green component of the diffuse color between [0.0, 1.0].
6536 * @param b Blue component of the diffuse color between [0.0, 1.0].
6537 * @param a Alpha component of the diffuse color between [0.0, 1.0].
6538 *
6539 * Default diffuse color is (1.0, 1.0, 1.0, 1.0).
6540 *
6541 * @ingroup Evas_3D_Light
6542 */
6543EAPI void evas_3d_light_diffuse_set(Evas_3D_Light *light, Evas_Real r, Evas_Real g, Evas_Real b, Evas_Real a) EINA_ARG_NONNULL(1);
6544
6545/**
6546 * Get the diffuse color of the given light.
6547 *
6548 * @param light The given light.
6549 * @param r Pointer to receive the red component of the diffuse color.
6550 * @param g Pointer to receive the green component of the diffuse color.
6551 * @param b Pointer to receive the blue component of the diffuse color.
6552 * @param a Pointer to receive the alpha component of the diffuse color.
6553 *
6554 * @see evas_3d_light_diffuse_set()
6555 *
6556 * @ingroup Evas_3D_Light
6557 */
6558EAPI void evas_3d_light_diffuse_get(const Evas_3D_Light *light, Evas_Real *r, Evas_Real *g, Evas_Real *b, Evas_Real *a) EINA_ARG_NONNULL(1);
6559
6560/**
6561 * Get the specular color of the given light.
6562 *
6563 * @param light The given light.
6564 * @param r Pointer to receive the red component of the specular color.
6565 * @param g Pointer to receive the green component of the specular color.
6566 * @param b Pointer to receive the blue component of the specular color.
6567 * @param a Pointer to receive the alpha component of the specular color.
6568 *
6569 * Default specular color is (1.0, 1.0, 1.0, 1.0).
6570 *
6571 * @ingroup Evas_3D_Light
6572 */
6573EAPI void evas_3d_light_specular_set(Evas_3D_Light *light, Evas_Real r, Evas_Real g, Evas_Real b, Evas_Real a) EINA_ARG_NONNULL(1);
6574
6575/**
6576 * Get the specular color of the given light.
6577 *
6578 * @param light The given light.
6579 * @param r Pointer to receive the red component of the specular color.
6580 * @param g Pointer to receive the green component of the specular color.
6581 * @param b Pointer to receive the blue component of the specular color.
6582 * @param a Pointer to receive the alpha component of the specular color.
6583 *
6584 * @see evas_3d_light_specular_set()
6585 *
6586 * @ingroup Evas_3D_Light
6587 */
6588EAPI void evas_3d_light_specular_get(const Evas_3D_Light *light, Evas_Real *r, Evas_Real *g, Evas_Real *b, Evas_Real *a) EINA_ARG_NONNULL(1);
6589
6590/**
6591 * Set the spot exponent of the given light.
6592 *
6593 * @param light The given light.
6594 * @param exponent Spot exponent value.
6595 *
6596 * Higher spot exponent means intensity at the center of the cone is relatively
6597 * stronger. Zero exponent means the light intensity is evenly distibuted. The
6598 * spot exponent has no effect when the light is not spot light (spot cutoff
6599 * angle is less than 180 degree).
6600 *
6601 * Default spot exponent is 0.
6602 *
6603 * @see evas_3d_light_spot_cutoff_set()
6604 *
6605 * @ingroup Evas_3D_Light
6606 */
6607EAPI void evas_3d_light_spot_exponent_set(Evas_3D_Light *light, Evas_Real exponent) EINA_ARG_NONNULL(1);
6608
6609/**
6610 * Get the spot exponent of the given light.
6611 *
6612 * @param light The given light.
6613 * @return The spot exponent value.
6614 *
6615 * @see evas_3d_light_spot_exponent_set()
6616 *
6617 * @ingroup Evas_3D_Light
6618 */
6619EAPI Evas_Real evas_3d_light_spot_exponent_get(const Evas_3D_Light *light) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6620
6621/**
6622 * Set the spot cutoff angle of the given light.
6623 *
6624 * @param light The given light.
6625 * @param cutoff Cutoff angle in degree.
6626 *
6627 * Only angle less than 180 degree will make it spot light, so that other spot
6628 * light attribute will take effect.
6629 *
6630 * Default spot cutoff angle is 180.
6631 *
6632 * @ingroup Evas_3D_Light
6633 */
6634EAPI void evas_3d_light_spot_cutoff_set(Evas_3D_Light *light, Evas_Real cutoff) EINA_ARG_NONNULL(1);
6635
6636/**
6637 * Get the spot cutoff angle of the given light.
6638 *
6639 * @param light The given light.
6640 * @return Cutoff angle in degree.
6641 *
6642 * @see evas_3d_light_spot_cutoff_set()
6643 *
6644 * @ingroup Evas_3D_Light
6645 */
6646EAPI Evas_Real evas_3d_light_spot_cutoff_get(const Evas_3D_Light *light) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6647
6648/**
6649 * Set the attenuation of the given light.
6650 *
6651 * @param light The given light.
6652 * @param constant Constant attenuation term.
6653 * @param linear Linear attenuation term.
6654 * @param quadratic Quadratic attenuation term.
6655 *
6656 * Light attenuation has no effect with directional light. And the attenuation
6657 * should be enabled first to take effect. The attenuation factor is calculated
6658 * as follows.
6659 *
6660 * atten = 1.0 / constant + linear * distance + quadratic * distance * distance
6661 *
6662 * Default attenuation is constant = 1.0, linear = 0.0, quadratic = 0.0.
6663 *
6664 * @see evas_3d_light_attenuation_enable_set()
6665 *
6666 * @ingroup Evas_3D_Light
6667 */
6668EAPI void evas_3d_light_attenuation_set(Evas_3D_Light *light, Evas_Real constant, Evas_Real linear, Evas_Real quadratic) EINA_ARG_NONNULL(1);
6669
6670/**
6671 * Get the attenuation of the given light.
6672 *
6673 * @param light The given light.
6674 * @param constant Pointer to receive constant attenuation term.
6675 * @param linear Pointer to receive linear attenuation term.
6676 * @param quadratic Pointer to receive quadratic attenuation term.
6677 *
6678 * @see evas_3d_light_attenuation_set()
6679 *
6680 * @ingroup Evas_3D_Light
6681 */
6682EAPI void evas_3d_light_attenuation_get(const Evas_3D_Light *light, Evas_Real *constant, Evas_Real *linear, Evas_Real *quadratic) EINA_ARG_NONNULL(1);
6683
6684/**
6685 * Set the attenuation enable flag of the given light.
6686 *
6687 * @param light The given light.
6688 * @param enable Whether to enable attenuation (@c EINA_TRUE), or not (@c EINA_FALSE).
6689 *
6690 * By default, light attenuation is not enabled.
6691 *
6692 * @see evas_3d_light_attenuation_set()
6693 *
6694 * @ingroup Evas_3D_Light
6695 */
6696EAPI void evas_3d_light_attenuation_enable_set(Evas_3D_Light *light, Eina_Bool enable) EINA_ARG_NONNULL(1);
6697
6698/**
6699 * Get the attenuation enable flag of the given light.
6700 *
6701 * @param light The given light.
6702 * @return @c EINA_TRUE if enabled, or @c EINA_FALSE if not.
6703 *
6704 * @see evas_3d_light_attenuation_enable_set()
6705 *
6706 * @ingroup Evas_3D_Light
6707 */
6708EAPI Eina_Bool evas_3d_light_attenuation_enable_get(const Evas_3D_Light *light) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6709
6710/**
6711 * Create a new mesh on the given Evas @p canvas.
6712 *
6713 * @param e The given canvas.
6714 * @return The created mesh handle.
6715 *
6716 * @ingroup Evas_3D_Mesh
6717 */
6718EAPI Evas_3D_Mesh *evas_3d_mesh_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6719
6720/**
6721 * Delete a mesh from its belonging Evas canvas.
6722 *
6723 * @param mesh The given mesh.
6724 *
6725 * @see evas_3d_mesh_add()
6726 *
6727 * @ingroup Evas_3D_Mesh
6728 */
6729EAPI void evas_3d_mesh_del(Evas_3D_Mesh *mesh) EINA_ARG_NONNULL(1);
6730
6731/**
6732 * Get the Evas canvas where the given node belongs to.
6733 *
6734 * @param mesh The given mesh.
6735 * @return The Evas canvas.
6736 *
6737 * @see evas_3d_mesh_add()
6738 *
6739 * @ingroup Evas_3D_Mesh
6740 */
6741EAPI Evas *evas_3d_mesh_evas_get(const Evas_3D_Mesh *mesh) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6742
6743/**
6744 * Set the shade mode of the given mesh.
6745 *
6746 * @param mesh The given mesh.
6747 * @param mode The shade mode.
6748 *
6749 * Default shade mode is EVAS_3D_SHADE_MODE_VERTEX_COLOR.
6750 *
6751 * @ingroup Evas_3D_Mesh
6752 */
6753EAPI void evas_3d_mesh_shade_mode_set(Evas_3D_Mesh *mesh, Evas_3D_Shade_Mode mode) EINA_ARG_NONNULL(1);
6754
6755/**
6756 * Get the shade mode of the given mesh.
6757 *
6758 * @param mesh The given mesh.
6759 * @return The shade mode.
6760 *
6761 * @see eavs_3d_mesh_shade_mode_set()
6762 *
6763 * @ingroup Evas_3D_Mesh
6764 */
6765EAPI Evas_3D_Shade_Mode evas_3d_mesh_shade_mode_get(const Evas_3D_Mesh *mesh) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6766
6767/**
6768 * Load mesh data from file.
6769 *
6770 * @param mesh The given mesh.
6771 * @param type The type of the mesh file.
6772 * @param file Path to the mesh file.
6773 * @param key Key in the mesh file.
6774 *
6775 * Loading a mesh from existing file is supported. Currently, only MD2 file
6776 * format is supported.
6777 *
6778 * @ingroup Evas_3D_Mesh
6779 */
6780EAPI void evas_3d_mesh_file_set(Evas_3D_Mesh *mesh, Evas_3D_Mesh_File_Type type, const char *file, const char *key) EINA_ARG_NONNULL(1);
6781
6782/**
6783 * Set the vertex count of the given mesh.
6784 *
6785 * @param mesh The given mesh.
6786 * @param count Vertex count.
6787 *
6788 * Each key frame should have same vertex count to be properly interpolated.
6789 * Key frames have their own vertex data and the data should have more vertices
6790 * than the mesh's vertex count.
6791 *
6792 * Default vertex count is 0.
6793 *
6794 * @ingroup Evas_3D_Mesh
6795 */
6796EAPI void evas_3d_mesh_vertex_count_set(Evas_3D_Mesh *mesh, unsigned int count) EINA_ARG_NONNULL(1);
6797
6798/**
6799 * Get the vertex count of the given mesh.
6800 *
6801 * @param mesh The given mesh.
6802 * @return Vertex count.
6803 *
6804 * @see evas_3d_mesh_vertex_count_set()
6805 *
6806 * @ingroup Evas_3D_Mesh
6807 */
6808EAPI int evas_3d_mesh_vertex_count_get(const Evas_3D_Mesh *mesh) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6809
6810/**
6811 * Add a key frame to the given mesh.
6812 *
6813 * @param mesh The given mesh.
6814 * @param frame The number of the key frame to be added.
6815 *
6816 * If specified frame is already exist, error message will be generated.
6817 *
6818 * @ingroup Evas_3D_Mesh
6819 */
6820EAPI void evas_3d_mesh_frame_add(Evas_3D_Mesh *mesh, int frame) EINA_ARG_NONNULL(1);
6821
6822/**
6823 * Delete a key frame from the given mesh.
6824 *
6825 * @param mesh The given mesh.
6826 * @param frame The number of the key frame to be deleted.
6827 *
6828 * @see evas_3d_mesh_frame_add()
6829 *
6830 * @ingroup Evas_3D_Mesh
6831 */
6832EAPI void evas_3d_mesh_frame_del(Evas_3D_Mesh *mesh, int frame) EINA_ARG_NONNULL(1);
6833
6834/**
6835 * Set the material of the key frame of the given mesh.
6836 *
6837 * @param mesh The given mesh.
6838 * @param frame The number of the key frame.
6839 * @param material The material to be set to the key frame.
6840 *
6841 * Setting different materials for each key frame is useful for doing animations
6842 * like GIF images or color changing animationas.
6843 *
6844 * @ingroup Evas_3D_Mesh
6845 */
6846EAPI void evas_3d_mesh_frame_material_set(Evas_3D_Mesh *mesh, int frame, Evas_3D_Material *material) EINA_ARG_NONNULL(1);
6847
6848/**
6849 * Get the material of the key frame of the given mesh.
6850 *
6851 * @param mesh The given mesh.
6852 * @param frame The number of the key frame.
6853 * @return The material of the key frame.
6854 *
6855 * @see evas_3d_mesh_frame_material_set()
6856 *
6857 * @ingroup Evas_3D_Mesh
6858 */
6859EAPI Evas_3D_Material *evas_3d_mesh_frame_material_get(const Evas_3D_Mesh *mesh, int frame) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6860
6861/**
6862 * Set the vertex data of the key frame of the given mesh.
6863 *
6864 * @param mesh The given mesh.
6865 * @param frame The number of the key frame.
6866 * @param attrib Vertex attribute ID.
6867 * @param stride Stride to go to the next vertex (in bytes).
6868 * @param data Pointer to the vertex data buffer.
6869 *
6870 * This function make evas read from the given buffer whenever it requires.
6871 * If you want to release the buffer after calling this functions, use
6872 * evas_3d_mesh_frame_vertex_data_copy_set() instead.
6873 *
6874 * After setting the vertex data, further modifications should be protected
6875 * by map/unmap pair.
6876 *
6877 * @see evas_3d_mesh_frame_vertex_data_copy_set()
6878 * @see evas_3d_mesh_frame_vertex_data_map()
6879 * @see evas_3d_mesh_frame_vertex_data_unmap()
6880 *
6881 * @ingroup Evas_3D_Mesh
6882 */
6883EAPI void evas_3d_mesh_frame_vertex_data_set(Evas_3D_Mesh *mesh, int frame, Evas_3D_Vertex_Attrib attrib, int stride, const void *data) EINA_ARG_NONNULL(1);
6884
6885/**
6886 * Set the vertex data of the key frame of the given mesh by copying from a buffer.
6887 *
6888 * @param mesh The given mesh.
6889 * @param frame The number of the key frame.
6890 * @param attrib Vertex attribute ID.
6891 * @param stride Stride to go to the next vertex (in bytes).
6892 * @param data Pointer to the vertex data buffer.
6893 *
6894 * This function allocates internal vertex buffer and copy from the given
6895 * buffer. So you can release the buffer. If you want to modify the vertex data
6896 * use evas_3d_mesh_frame_vertex_data_map(). After finishing the modifications,
6897 * you should call evas_3d_mesh_frame_vertex_data_unmap().
6898 *
6899 * @see evas_3d_mesh_frame_vertex_data_set()
6900 * @see evas_3d_mesh_frame_vertex_data_map()
6901 * @see evas_3d_mesh_frame_vertex_data_unmap()
6902 *
6903 * @ingroup Evas_3D_Mesh
6904 */
6905EAPI void evas_3d_mesh_frame_vertex_data_copy_set(Evas_3D_Mesh *mesh, int frame, Evas_3D_Vertex_Attrib attrib, int stride, const void *data) EINA_ARG_NONNULL(1);
6906
6907/**
6908 * Map the vertex buffer of the key frame of the given mesh.
6909 *
6910 * @param mesh The given mesh.
6911 * @param frame The number of the key frame.
6912 * @param attrib Vertex attribute ID.
6913 * @return Starting address of the mapped vertex buffer.
6914 *
6915 * After manipulating the mapped buffer, evas_3d_mesh_frame_vertex_data_unmap()
6916 * should be called to properly download the data to the engine. If the data
6917 * was set using evas_3d_mesh_frame_vertex_data_set(), pointer to the original
6918 * buffer will be returned. Otherwise, the returned pointer can differ every
6919 * time calling this function.
6920 *
6921 * @see evas_3d_mesh_frame_vertex_data_unmap()
6922 *
6923 * @ingroup Evas_3D_Mesh
6924 */
6925EAPI void *evas_3d_mesh_frame_vertex_data_map(Evas_3D_Mesh *mesh, int frame, Evas_3D_Vertex_Attrib attrib) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6926
6927/**
6928 * Unmap the vertex buffer of the key frame of the given mesh.
6929 *
6930 * @param mesh The given mesh.
6931 * @param frame The number of the key frame.
6932 * @param attrib Vertex attribute ID.
6933 *
6934 * @see evas_3d_mesh_frame_vertex_data_map()
6935 *
6936 * @ingroup Evas_3D_Mesh
6937 */
6938EAPI void evas_3d_mesh_frame_vertex_data_unmap(Evas_3D_Mesh *mesh, int frame, Evas_3D_Vertex_Attrib attrib) EINA_ARG_NONNULL(1);
6939
6940/**
6941 * Get the vertex buffer stride of the key frame of the given mesh.
6942 *
6943 * @param mesh The given mesh.
6944 * @param frame The number of the key frame.
6945 * @param attrib Vertex attribute ID.
6946 * @return Stride to go to the next vertex (in bytes).
6947 *
6948 * This function returns valid stride only when the vertex buffer is mapped.
6949 * If the data was set with evas_3d_mesh_frame_vertex_data_set(), the original
6950 * stride will be returned unchanged.
6951 *
6952 * @see evas_3d_mesh_frame_vertex_data_map()
6953 *
6954 * @ingroup Evas_3D_Mesh
6955 */
6956EAPI int evas_3d_mesh_frame_vertex_stride_get(const Evas_3D_Mesh *mesh, int frame, Evas_3D_Vertex_Attrib attrib) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
6957
6958/**
6959 * Set the vertex index data of the given mesh.
6960 *
6961 * @param mesh The given mesh.
6962 * @param format Vertex index data format.
6963 * @param count Vertex index count.
6964 * @param indices Pointer to the index data.
6965 *
6966 * When the index data is set, Evas 3D assembles vertices using the index data.
6967 * If you want to free the data buffer, use evas_3d_mesh_index_data_copy_set().
6968 * Further modifications should be made within map/unmap pair.
6969 *
6970 * @see evas_3d_mesh_index_data_copy_set()
6971 * @see evas_3d_mesh_index_data_map()
6972 * @see evas_3d_mesh_index_data_unmap()
6973 *
6974 * @ingroup Evas_3D_Mesh
6975 */
6976EAPI void evas_3d_mesh_index_data_set(Evas_3D_Mesh *mesh, Evas_3D_Index_Format format, int count, const void *indices) EINA_ARG_NONNULL(1);
6977
6978/**
6979 * Set the vertex index data of the given mesh by copying from a buffer.
6980 *
6981 * @param mesh The given mesh.
6982 * @param format Vertex index data format.
6983 * @param count Vertex index count.
6984 * @param indices Pointer to the vertex data.
6985 *
6986 * This function allocates internal index buffer any copy data from the given
6987 * buffer. Futher modifications can be made within map/unmap pair.
6988 *
6989 * @see evas_3d_mesh_index_data_set()
6990 *
6991 * @ingroup Evas_3D_Mesh
6992 */
6993EAPI void evas_3d_mesh_index_data_copy_set(Evas_3D_Mesh *mesh, Evas_3D_Index_Format format, int count, const void *indices) EINA_ARG_NONNULL(1);
6994
6995/**
6996 * Get the format of the index data of the given mesh.
6997 *
6998 * @param mesh The given mesh.
6999 * @return Format of the index data.
7000 *
7001 * Returns valid format only when the index buffer is mapped. First map the
7002 * index buffer and then query the properties of the mapped buffer. If the index
7003 * data was set by evas_3d_mesh_index_data_set(), the original format will be
7004 * returned. Otherwise the format can differ every time you call the
7005 * evas_3d_mesh_index_data_map() function.
7006 *
7007 * @see evas_3d_mesh_index_data_map()
7008 *
7009 * @ingroup Evas_3D_Mesh
7010 */
7011EAPI Evas_3D_Index_Format evas_3d_mesh_index_format_get(const Evas_3D_Mesh *mesh) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7012
7013/**
7014 * Get the count of the index data of the given mesh.
7015 *
7016 * @param mesh The given mesh.
7017 * @return Index data count.
7018 *
7019 * This function returns the index count of the last called data_set function.
7020 *
7021 * @see evas_3d_mesh_index_data_set()
7022 * @see evas_3d_mesh_index_data_copy_set()
7023 *
7024 * @ingroup Evas_3D_Mesh
7025 */
7026EAPI int evas_3d_mesh_index_count_get(const Evas_3D_Mesh *mesh) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7027
7028/**
7029 * Map the index buffer of the given mesh.
7030 *
7031 * @param mesh The given mesh.
7032 * @return Pointer to the mapped buffer.
7033 *
7034 * evas_3d_mesh_index_data_unmap() should be called after modifications. If the
7035 * data was set using evas_3d_mesh_index_data_set(), the original pointer will
7036 * be returned, otherwise, the returned pointer may differ every time you call
7037 * this function.
7038 *
7039 * @see evas_3d_mesh_index_data_unmap()
7040 *
7041 * @ingroup Evas_3D_Mesh
7042 */
7043EAPI void *evas_3d_mesh_index_data_map(Evas_3D_Mesh *mesh) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7044
7045/**
7046 * Unmap the index buffer of the given mesh.
7047 *
7048 * @param mesh The given mesh.
7049 *
7050 * @see evas_3d_mesh_index_data_map()
7051 *
7052 * @ingroup Evas_3D_Mesh
7053 */
7054EAPI void evas_3d_mesh_index_data_unmap(Evas_3D_Mesh *mesh) EINA_ARG_NONNULL(1);
7055
7056/**
7057 * Set the vertex assembly of the given mesh.
7058 *
7059 * @param mesh The given mesh.
7060 * @param assembly Vertex assembly.
7061 *
7062 * Vertex assembly defines how the engine organizes vertices into geometric
7063 * primitives.
7064 *
7065 * Default vertex assembly is EVAS_3D_VERTEX_ASSEMBLY_TRIANGLES.
7066 *
7067 * @ingroup Evas_3D_Mesh
7068 */
7069EAPI void evas_3d_mesh_vertex_assembly_set(Evas_3D_Mesh *mesh, Evas_3D_Vertex_Assembly assembly);
7070
7071/**
7072 * Get the vertex assembly of the given mesh.
7073 *
7074 * @param mesh The given mesh.
7075 * @return The vertex assembly.
7076 *
7077 * @see evas_3d_mesh_vertex_assembly_set()
7078 *
7079 * @ingroup Evas_3D_Mesh
7080 */
7081EAPI Evas_3D_Vertex_Assembly evas_3d_mesh_vertex_assembly_get(const Evas_3D_Mesh *mesh);
7082
7083/**
7084 * Create a new texture on the given Evas @p canvas.
7085 *
7086 * @param e The given canvas.
7087 * @return The created texture handle.
7088 *
7089 * @ingroup Evas_3D_Texture
7090 */
7091EAPI Evas_3D_Texture *evas_3d_texture_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7092
7093/**
7094 * Delete a texture from its belonging Evas canvas.
7095 *
7096 * @param texture The given texture.
7097 *
7098 * @see evas_3d_texture_add()
7099 *
7100 * @ingroup Evas_3D_Texture
7101 */
7102EAPI void evas_3d_texture_del(Evas_3D_Texture *texture) EINA_ARG_NONNULL(1);
7103
7104/**
7105 * Get the Evas canvas where the given texture belongs to.
7106 *
7107 * @param texture The given texture.
7108 * @return The Evas canvas.
7109 *
7110 * @see evas_3d_texture_add()
7111 *
7112 * @ingroup Evas_3D_Texture
7113 */
7114EAPI Evas *evas_3d_texture_evas_get(const Evas_3D_Texture *texture) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7115
7116/**
7117 * Set the data of the given texture.
7118 *
7119 * @param texure The given texture
7120 * @param color_format Color format of the texture.
7121 * @param pixel_format Pixel format of the data.
7122 * @param w Width of the data.
7123 * @param h Height of the data.
7124 * @param data Pointer to the data.
7125 *
7126 * @see evas_3d_texture_file_set()
7127 *
7128 * @ingroup Evas_3D_Texture
7129 */
7130EAPI void evas_3d_texture_data_set(Evas_3D_Texture *texture, Evas_3D_Color_Format color_format, Evas_3D_Pixel_Format pixel_format, int w, int h, const void *data);
7131
7132/**
7133 * Set the data of the given texture from file.
7134 *
7135 * @param texture The given texture.
7136 * @param file Path to the image file.
7137 * @param key Key in the image file.
7138 *
7139 * Only PNG format is supported.
7140 *
7141 * @ingroup Evas_3D_Texture
7142 */
7143EAPI void evas_3d_texture_file_set(Evas_3D_Texture *texture, const char *file, const char *key) EINA_ARG_NONNULL(1);
7144
7145/**
7146 * Set the data of the given texture from an evas object.
7147 *
7148 * @param texture The given texture.
7149 * @param source Source evas object to be used as the texture data.
7150 *
7151 * Evas 3D support using existing evas object as a texture source. This feature
7152 * make it possible using any exisiting evas object inside 3D scene.
7153 *
7154 * @see evas_3d_texture_source_visible_set
7155 *
7156 * @ingroup Evas_3D_Texture
7157 */
7158EAPI void evas_3d_texture_source_set(Evas_3D_Texture *texture, Evas_Object *source) EINA_ARG_NONNULL(1);
7159
7160/**
7161 * Set the visibility flag of the source evas object of the given texture.
7162 *
7163 * @param texture The given texture.
7164 * @param visible @c EINA_TRUE for visible, @c EINA_FALSE for invisible.
7165 *
7166 * Recommend to call evas_object_show() on the source object and controll the
7167 * visibility using this function.
7168 *
7169 * By default, source object is visible.
7170 *
7171 * @see evas_3d_texture_source_set()
7172 *
7173 * @ingroup Evas_3D_Texture
7174 */
7175EAPI void evas_3d_texture_source_visible_set(Evas_3D_Texture *texture, Eina_Bool visible) EINA_ARG_NONNULL(1);
7176
7177/**
7178 * Get the visibility flag of the source evas object of the given texture.
7179 *
7180 * @param texture The given texture.
7181 * @return @c EINA_TRUE if visible, @c EINA_FALSE if invisible.
7182 *
7183 * @see evas_3d_texture_source_visible_set()
7184 *
7185 * @ingroup Evas_3D_Texture
7186 */
7187EAPI Eina_Bool evas_3d_texture_source_visible_get(const Evas_3D_Texture *texture) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7188
7189/**
7190 * Get the color format of the given texture.
7191 *
7192 * @param texture The given texture.
7193 *
7194 * EVAS_3D_COLOR_FORMAT_RGBA will be returned if the texture has source object.
7195 * Otherwise, the color format of the data will be returned.
7196 *
7197 * @see evas_3d_texture_data_set()
7198 * @see evas_3d_texture_file_set()
7199 * @see evas_3d_texture_source_set()
7200 *
7201 * @ingroup Evas_3D_Texture
7202 */
7203EAPI Evas_3D_Color_Format evas_3d_texture_color_format_get(const Evas_3D_Texture *texture) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7204
7205/**
7206 * Get the size of the given texture.
7207 *
7208 * @param texture The given texture.
7209 * @param w Pointer to receive the width of the texture size.
7210 * @param h Pointer to receive the height of the texture size.
7211 *
7212 * If the texture has source object, the size of the source object will be
7213 * returned. Otherwise, the size of the data (or image file) will be returned.
7214 *
7215 * @see evas_3d_texture_data_set()
7216 * @see evas_3d_texture_file_set()
7217 * @see evas_3d_texture_source_set()
7218 *
7219 * @ingroup Evas_3D_Texture
7220 */
7221EAPI void evas_3d_texture_size_get(const Evas_3D_Texture *texture, int *w, int *h) EINA_ARG_NONNULL(1);
7222
7223/**
7224 * Set the wrap mode of the given texture.
7225 *
7226 * @param texture The given texture.
7227 * @param s Wrap mode for S-axis.
7228 * @param t Wrap mode for T-axis.
7229 *
7230 * If the texture coordinate exceed range [0.0, 1.0] the values are modified
7231 * according to the wrap mode.
7232 *
7233 * Default wrap modes are both EVAS_3D_WRAP_MODE_CLAMP for s and t.
7234 *
7235 * @ingroup Evas_3D_Texture
7236 */
7237EAPI void evas_3d_texture_wrap_set(Evas_3D_Texture *texture, Evas_3D_Wrap_Mode s, Evas_3D_Wrap_Mode t) EINA_ARG_NONNULL(1);
7238
7239/**
7240 * Get the wrap mode of the given texture.
7241 *
7242 * @param texture The given texture.
7243 * @param s Pointer to receive S-axis wrap mode.
7244 * @param t Pointer to receive T-axis wrap mode.
7245 *
7246 * @see evas_3d_texture_wrap_set()
7247 *
7248 * @ingroup Evas_3D_Texture
7249 */
7250EAPI void evas_3d_texture_wrap_get(Evas_3D_Texture *texture, Evas_3D_Wrap_Mode *s, Evas_3D_Wrap_Mode *t) EINA_ARG_NONNULL(1);
7251
7252/**
7253 * Set the filter of the given texture.
7254 *
7255 * @param texture The given texture.
7256 * @param min Minification filter used when down-scaling.
7257 * @param mag Magnification filter used when up-scaling.
7258 *
7259 * Default filters are both EVAS_3D_TEXTURE_FILTER_NEAREST for s and t.
7260 *
7261 * @ingroup Evas_3D_Texture
7262 */
7263EAPI void evas_3d_texture_filter_set(Evas_3D_Texture *texture, Evas_3D_Texture_Filter min, Evas_3D_Texture_Filter mag) EINA_ARG_NONNULL(1);
7264
7265/**
7266 * Get the filter of the given texture.
7267 *
7268 * @param texture The given texture.
7269 * @param min Pointer to receive the minification filter.
7270 * @param mag Pointer to receive the magnification filter.
7271 *
7272 * @see evas_3d_texture_filter_set()
7273 *
7274 * @ingroup Evas_3D_Texture
7275 */
7276EAPI void evas_3d_texture_filter_get(const Evas_3D_Texture *texture, Evas_3D_Texture_Filter *min, Evas_3D_Texture_Filter *mag) EINA_ARG_NONNULL(1);
7277
7278/**
7279 * Create a new material on the given Evas @p canvas.
7280 *
7281 * @param e The given canvas.
7282 * @param type The type of the material.
7283 * @return The created material handle.
7284 *
7285 * @ingroup Evas_3D_Material
7286 */
7287EAPI Evas_3D_Material *evas_3d_material_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7288
7289/**
7290 * Delete a material from its belonging Evas canvas.
7291 *
7292 * @param material The given material.
7293 *
7294 * @see evas_3d_material_add()
7295 *
7296 * @ingroup Evas_3D_Material
7297 */
7298EAPI void evas_3d_material_del(Evas_3D_Material *material) EINA_ARG_NONNULL(1);
7299
7300/**
7301 * Get the Evas canvas where the given material belongs to.
7302 *
7303 * @param material The given material.
7304 * @return The Evas canvas.
7305 *
7306 * @see evas_3d_material_add()
7307 *
7308 * @ingroup Evas_3D_Material
7309 */
7310EAPI Evas *evas_3d_material_evas_get(const Evas_3D_Material *material) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7311
7312/**
7313 * Set the material attribute enable flag of the given material.
7314 *
7315 * @param material The given material.
7316 * @param attrib Material attribute ID.
7317 * @param enable Whether to enable the attribute (@c EINA_TRUE), or not (@c EINA_FALSE).
7318 *
7319 * You might want to disable some material reflection contribution. For
7320 * example,Emission attribute is rarely used. Disabling unused attributes
7321 * might help the shading less complex so that can get speed up.
7322 *
7323 * By default, diffuse and specular is enabled.
7324 *
7325 * @ingroup Evas_3D_Material
7326 */
7327EAPI void evas_3d_material_enable_set(Evas_3D_Material *material, Evas_3D_Material_Attrib attrib, Eina_Bool enable) EINA_ARG_NONNULL(1);
7328
7329/**
7330 * Get the material attribute enable flag of the given material.
7331 *
7332 * @param material The given material.
7333 * @param attrib Material attribute ID.
7334 * @return @c EINA_TRUE if enabled, or @c EINA_FALSE if not.
7335 *
7336 * @see evas_3d_material_enable_set()
7337 *
7338 * @ingroup Evas_3D_Material
7339 */
7340EAPI Eina_Bool evas_3d_material_enable_get(const Evas_3D_Material *material, Evas_3D_Material_Attrib attrib) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7341
7342/**
7343 * Set the material attribute color of the given material.
7344 *
7345 * @param material The given material.
7346 * @param attrib Material attribute ID.
7347 * @param r Red component of the color.
7348 * @param g Green component of the color.
7349 * @param b Blue component of the color.
7350 * @param a Alpha component of the color.
7351 *
7352 * Material color is used also when texture map is enabled. The colors will be
7353 * modulated (multiplied). To controll the color contribution of a material
7354 * attribute, use gray color. Setting color value for normal attribute has no
7355 * effect.
7356 *
7357 * Default color is as follows.
7358 *
7359 * Ambient : (0.2, 0.2, 0.2, 1.0)
7360 * Diffuse : (0.8, 0.8, 0.8, 1.0)
7361 * Specular : (1.0, 1.0, 1.0, 1.0)
7362 * Emission : (0.0, 0.0, 0.0, 1.0)
7363 * Normal : Not used
7364 *
7365 * @ingroup Evas_3D_Material
7366 */
7367EAPI void evas_3d_material_color_set(Evas_3D_Material *material, Evas_3D_Material_Attrib attrib, Evas_Real r, Evas_Real g, Evas_Real b, Evas_Real a) EINA_ARG_NONNULL(1);
7368
7369/**
7370 * Get the material attribute color of the given material.
7371 *
7372 * @param material The given material.
7373 * @param attrib Material attribute ID.
7374 * @param r Pointer to receive red component of the color.
7375 * @param g Pointer to receive green component of the color.
7376 * @param b Pointer to receive blue component of the color.
7377 * @param a Pointer to receive alpha component of the color.
7378 *
7379 * @see evas_3d_material_color_set()
7380 *
7381 * @ingroup Evas_3D_Material
7382 */
7383EAPI void evas_3d_material_color_get(const Evas_3D_Material *material, Evas_3D_Material_Attrib attrib, Evas_Real *r, Evas_Real *g, Evas_Real *b, Evas_Real *a) EINA_ARG_NONNULL(1);
7384
7385/**
7386 * Set the shininess of the given material.
7387 *
7388 * @param material The given material.
7389 * @param shininess Shininess value.
7390 *
7391 * Shininess is only used when specular attribute is enabled. Higher shininess
7392 * value will make the object more shiny.
7393 *
7394 * Default shininess value is 150.0.
7395 *
7396 * @see evas_3d_material_enable_set()
7397 *
7398 * @ingroup Evas_3D_Material
7399 */
7400EAPI void evas_3d_material_shininess_set(Evas_3D_Material *material, Evas_Real shininess) EINA_ARG_NONNULL(1);
7401
7402/**
7403 * Get the shininess of the given material.
7404 *
7405 * @param material The given material.
7406 * @return The shininess value.
7407 *
7408 * @see evas_3d_material_shininess_set()
7409 *
7410 * @ingroup Evas_3D_Material
7411 */
7412EAPI Evas_Real evas_3d_material_shininess_get(const Evas_3D_Material *material) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7413
7414/**
7415 * Set the texture of the given material.
7416 *
7417 * @param material The given material.
7418 * @param attrib Material attribute ID.
7419 * @param texture Texture to be set.
7420 *
7421 * You have to enable the desired attribute first.
7422 *
7423 * @see evas_3d_material_enable_set()
7424 *
7425 * @ingroup Evas_3D_Material
7426 */
7427EAPI void evas_3d_material_texture_set(Evas_3D_Material *material, Evas_3D_Material_Attrib attrib, Evas_3D_Texture *texture) EINA_ARG_NONNULL(1);
7428
7429/**
7430 * Get the texture of the given material.
7431 *
7432 * @param material The given material.
7433 * @param attrib Material attribute ID.
7434 * @return The texture that is set to the given material attribute.
7435 *
7436 * @see evas_3d_material_texture_set()
7437 *
7438 * @ingroup Evas_3D_Material
7439 */
7440EAPI Evas_3D_Texture *evas_3d_material_texture_get(const Evas_3D_Material *material, Evas_3D_Material_Attrib attrib) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
7441