/usr/include/gstreamermm-1.0/gstreamermm/element.h is in libgstreamermm-1.0-dev 1.10.0+dfsg-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 | // Generated by gmmproc 2.50.1 -- DO NOT MODIFY!
#ifndef _GSTREAMERMM_ELEMENT_H
#define _GSTREAMERMM_ELEMENT_H
#include <glibmm/ustring.h>
#include <sigc++/sigc++.h>
/* gstreamermm - a C++ wrapper for gstreamer
*
* Copyright 2008-2016 The gstreamermm Development Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free
* Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
#include <gst/gstelement.h>
#include <gstreamermm/object.h>
#include <gstreamermm/clock.h>
#include <gstreamermm/enums.h>
#include <gstreamermm/error.h>
#include <gstreamermm/message.h>
#ifndef DOXYGEN_SHOULD_SKIP_THIS
using GstElement = struct _GstElement;
using GstElementClass = struct _GstElementClass;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Gst
{ class Element_Class; } // namespace Gst
#endif //DOXYGEN_SHOULD_SKIP_THIS
namespace Gst
{
/** @defgroup GstBaseClasses gstreamermm Base Classes
* Wrapped GStreamer base classes (plug-ins derrive from these).
*/
/** @defgroup GstPlugins gstreamermm Plugins
* Wrapped GStreamer plugins.
*/
/** @defgroup GstInterfaces gstreamermm Interfaces
* Wrapped GStreamer interfaces and classes related to them.
*/
class Bus;
class Caps;
class Context;
class ElementFactory;
class Event;
class Pad;
class PadTemplate;
class Query;
//Gst::Iterator<> forward declaration.
template <class CppType>
class Iterator;
/** @addtogroup gstreamermmEnums gstreamermm Enums and Flags */
/**
* @var ElementFlags ELEMENT_FLAG_LOCKED_STATE
* Ignore state changes from parent.
*
* @var ElementFlags ELEMENT_FLAG_SINK
* The element is a sink.
*
* @var ElementFlags ELEMENT_FLAG_SOURCE
* The element is a source.
*
* @var ElementFlags ELEMENT_FLAG_PROVIDE_CLOCK
* The element can provide a clock.
*
* @var ElementFlags ELEMENT_FLAG_REQUIRE_CLOCK
* The element requires a clock.
*
* @var ElementFlags ELEMENT_FLAG_INDEXABLE
* The element can use an index.
*
* @var ElementFlags ELEMENT_FLAG_LAST
* Offset to define more flags.
*
* @enum ElementFlags
*
* The standard flags that an element may have.
*
* @ingroup gstreamermmEnums
* @par Bitwise operators:
* <tt>%ElementFlags operator|(ElementFlags, ElementFlags)</tt><br>
* <tt>%ElementFlags operator&(ElementFlags, ElementFlags)</tt><br>
* <tt>%ElementFlags operator^(ElementFlags, ElementFlags)</tt><br>
* <tt>%ElementFlags operator~(ElementFlags)</tt><br>
* <tt>%ElementFlags& operator|=(ElementFlags&, ElementFlags)</tt><br>
* <tt>%ElementFlags& operator&=(ElementFlags&, ElementFlags)</tt><br>
* <tt>%ElementFlags& operator^=(ElementFlags&, ElementFlags)</tt><br>
*/
enum ElementFlags
{
ELEMENT_FLAG_LOCKED_STATE = (GST_OBJECT_FLAG_LAST << 0),
ELEMENT_FLAG_SINK = (GST_OBJECT_FLAG_LAST << 1),
ELEMENT_FLAG_SOURCE = (GST_OBJECT_FLAG_LAST << 2),
ELEMENT_FLAG_PROVIDE_CLOCK = (GST_OBJECT_FLAG_LAST << 3),
ELEMENT_FLAG_REQUIRE_CLOCK = (GST_OBJECT_FLAG_LAST << 4),
ELEMENT_FLAG_INDEXABLE = (GST_OBJECT_FLAG_LAST << 5),
ELEMENT_FLAG_LAST = (GST_OBJECT_FLAG_LAST << 10)
};
/** @ingroup gstreamermmEnums */
inline ElementFlags operator|(ElementFlags lhs, ElementFlags rhs)
{ return static_cast<ElementFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
/** @ingroup gstreamermmEnums */
inline ElementFlags operator&(ElementFlags lhs, ElementFlags rhs)
{ return static_cast<ElementFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
/** @ingroup gstreamermmEnums */
inline ElementFlags operator^(ElementFlags lhs, ElementFlags rhs)
{ return static_cast<ElementFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
/** @ingroup gstreamermmEnums */
inline ElementFlags operator~(ElementFlags flags)
{ return static_cast<ElementFlags>(~static_cast<unsigned>(flags)); }
/** @ingroup gstreamermmEnums */
inline ElementFlags& operator|=(ElementFlags& lhs, ElementFlags rhs)
{ return (lhs = static_cast<ElementFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
/** @ingroup gstreamermmEnums */
inline ElementFlags& operator&=(ElementFlags& lhs, ElementFlags rhs)
{ return (lhs = static_cast<ElementFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
/** @ingroup gstreamermmEnums */
inline ElementFlags& operator^=(ElementFlags& lhs, ElementFlags rhs)
{ return (lhs = static_cast<ElementFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
} // namespace Gst
#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Glib
{
template <>
class Value<Gst::ElementFlags> : public Glib::Value_Flags<Gst::ElementFlags>
{
public:
static GType value_type() G_GNUC_CONST;
};
} // namespace Glib
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
namespace Gst
{
/**
* @var StateChange STATE_CHANGE_NULL_TO_READY
* State change from <tt>nullptr</tt> to READY.
* -
* The element must check if the resources it needs are available. Device
* sinks and -sources typically try to probe the device to constrain their
* caps.
* -
* The element opens the device (in case feature need to be probed).
* .
*
* @var StateChange STATE_CHANGE_READY_TO_PAUSED
* State change from READY to PAUSED.
* -
* The element pads are activated in order to receive data in PAUSED.
* Streaming threads are started.
* -
* Some elements might need to return Gst::STATE_CHANGE_ASYNC and complete
* the state change when they have enough information. It is a requirement
* for sinks to return Gst::STATE_CHANGE_ASYNC and complete the state change
* when they receive the first buffer or Gst::EVENT_EOS (preroll).
* Sinks also block the dataflow when in PAUSED.
* -
* A pipeline resets the running_time to 0.
* -
* Live sources return Gst::STATE_CHANGE_NO_PREROLL and don't generate data.
* .
*
* @var StateChange STATE_CHANGE_PAUSED_TO_PLAYING
* State change from PAUSED to PLAYING.
* -
* Most elements ignore this state change.
* -
* The pipeline selects a Gst::Clock and distributes this to all the children
* before setting them to PLAYING. This means that it is only allowed to
* synchronize on the Gst::Clock in the PLAYING state.
* -
* The pipeline uses the Gst::Clock and the running_time to calculate the
* base_time. The base_time is distributed to all children when performing
* the state change.
* -
* Sink elements stop blocking on the preroll buffer or event and start
* rendering the data.
* -
* Sinks can post Gst::MESSAGE_EOS in the PLAYING state. It is not allowed
* to post Gst::MESSAGE_EOS when not in the PLAYING state.
* -
* While streaming in PAUSED or PLAYING elements can create and remove
* sometimes pads.
* -
* Live sources start generating data and return Gst::STATE_CHANGE_SUCCESS.
* .
*
* @var StateChange STATE_CHANGE_PLAYING_TO_PAUSED
* State change from PLAYING to PAUSED.
* -
* Most elements ignore this state change.
* -
* The pipeline calculates the running_time based on the last selected
* Gst::Clock and the base_time. It stores this information to continue
* playback when going back to the PLAYING state.
* -
* Sinks unblock any Gst::Clock wait calls.
* -
* When a sink does not have a pending buffer to play, it returns
* Gst::STATE_CHANGE_ASYNC from this state change and completes the state
* change when it receives a new buffer or an Gst::EVENT_EOS.
* -
* Any queued Gst::MESSAGE_EOS items are removed since they will be reposted
* when going back to the PLAYING state. The EOS messages are queued in
* Gst::Bin containers.
* -
* Live sources stop generating data and return Gst::STATE_CHANGE_NO_PREROLL.
* .
*
* @var StateChange STATE_CHANGE_PAUSED_TO_READY
* State change from PAUSED to READY.
* -
* Sinks unblock any waits in the preroll.
* -
* Elements unblock any waits on devices
* -
* Chain or get_range functions return Gst::FLOW_FLUSHING.
* -
* The element pads are deactivated so that streaming becomes impossible and
* all streaming threads are stopped.
* -
* The sink forgets all negotiated formats
* -
* Elements remove all sometimes pads
* .
*
* @var StateChange STATE_CHANGE_READY_TO_NULL
* State change from READY to <tt>nullptr</tt>.
* -
* Elements close devices
* -
* Elements reset any internal state.
* .
*
* @enum StateChange
*
* These are the different state changes an element goes through.
* Gst::STATE_NULL ⇒ Gst::STATE_PLAYING is called an upwards state change
* and Gst::STATE_PLAYING ⇒ Gst::STATE_NULL a downwards state change.
*
* @ingroup gstreamermmEnums
* @par Bitwise operators:
* <tt>%StateChange operator|(StateChange, StateChange)</tt><br>
* <tt>%StateChange operator&(StateChange, StateChange)</tt><br>
* <tt>%StateChange operator^(StateChange, StateChange)</tt><br>
* <tt>%StateChange operator~(StateChange)</tt><br>
* <tt>%StateChange& operator|=(StateChange&, StateChange)</tt><br>
* <tt>%StateChange& operator&=(StateChange&, StateChange)</tt><br>
* <tt>%StateChange& operator^=(StateChange&, StateChange)</tt><br>
*/
enum StateChange
{
STATE_CHANGE_NULL_TO_READY = 0xA,
STATE_CHANGE_READY_TO_PAUSED = 0x13,
STATE_CHANGE_PAUSED_TO_PLAYING = 0x1C,
STATE_CHANGE_PLAYING_TO_PAUSED = 0x23,
STATE_CHANGE_PAUSED_TO_READY = 0x1A,
STATE_CHANGE_READY_TO_NULL = 0x11
};
/** @ingroup gstreamermmEnums */
inline StateChange operator|(StateChange lhs, StateChange rhs)
{ return static_cast<StateChange>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
/** @ingroup gstreamermmEnums */
inline StateChange operator&(StateChange lhs, StateChange rhs)
{ return static_cast<StateChange>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
/** @ingroup gstreamermmEnums */
inline StateChange operator^(StateChange lhs, StateChange rhs)
{ return static_cast<StateChange>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
/** @ingroup gstreamermmEnums */
inline StateChange operator~(StateChange flags)
{ return static_cast<StateChange>(~static_cast<unsigned>(flags)); }
/** @ingroup gstreamermmEnums */
inline StateChange& operator|=(StateChange& lhs, StateChange rhs)
{ return (lhs = static_cast<StateChange>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
/** @ingroup gstreamermmEnums */
inline StateChange& operator&=(StateChange& lhs, StateChange rhs)
{ return (lhs = static_cast<StateChange>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
/** @ingroup gstreamermmEnums */
inline StateChange& operator^=(StateChange& lhs, StateChange rhs)
{ return (lhs = static_cast<StateChange>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
} // namespace Gst
#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Glib
{
template <>
class Value<Gst::StateChange> : public Glib::Value_Flags<Gst::StateChange>
{
public:
static GType value_type() G_GNUC_CONST;
};
} // namespace Glib
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
namespace Gst
{
/**
* @var StateChangeReturn STATE_CHANGE_FAILURE
* The state change failed.
*
* @var StateChangeReturn STATE_CHANGE_SUCCESS
* The state change succeeded.
*
* @var StateChangeReturn STATE_CHANGE_ASYNC
* The state change will happen asynchronously.
*
* @var StateChangeReturn STATE_CHANGE_NO_PREROLL
* The state change succeeded but the element
* cannot produce data in Gst::STATE_PAUSED.
* This typically happens with live sources.
*
* @enum StateChangeReturn
*
* The possible return values from a state change function such as
* Gst::Element::set_state(). Only @a GST_STATE_CHANGE_FAILURE is a real failure.
*
* @ingroup gstreamermmEnums
*/
enum StateChangeReturn
{
STATE_CHANGE_FAILURE,
STATE_CHANGE_SUCCESS,
STATE_CHANGE_ASYNC,
STATE_CHANGE_NO_PREROLL
};
} // namespace Gst
#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Glib
{
template <>
class Value<Gst::StateChangeReturn> : public Glib::Value_Enum<Gst::StateChangeReturn>
{
public:
static GType value_type() G_GNUC_CONST;
};
} // namespace Glib
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
namespace Gst
{
namespace Enums
{
/** Gets a string representing the given state.
*
* @param state A Gst::State to get the name of.
* @return A Glib::ustring with the name of the state.
*/
Glib::ustring get_name(State state);
/** Gets a string representing the given state change result.
*
* @param state_ret A Gst::StateChangeReturn to get the name of.
* @return A Glib::ustring with the name of the state change result.
*/
Glib::ustring get_name(StateChangeReturn state_ret);
} //namespace Enums
/** Abstract base class for all pipeline elements
*
* Gst::Element is the abstract base class needed to construct an element that
* can be used in a GStreamer pipeline. Please refer to the plugin writers
* guide for more information on creating Gst::Element subclasses.
*
* The name of a Gst::Element can be get with get_name() and set with
* set_name().
*
* Elements can have pads (of the type Gst::Pad). These pads link to pads on
* other elements. Gst::Buffer flow between these linked pads.
* A Gst::Element has a GList of Gst::Pad structures for all their input (or sink)
* and output (or source) pads.
* Core and plug-in writers can add and remove pads with add_pad()
* and remove_pad().
*
* An existing pad of an element can be retrieved by name with
* get_static_pad(). A new dynamic pad can be created using
* request_pad() with a Gst::PadTemplate.
* An iterator of all pads can be retrieved with iterate_pads().
*
* Elements can be linked through their pads.
* If the link is straightforward, use the link()
* convenience function to link two elements.
* Use link_filtered() to link two elements constrained by
* a specified set of Gst::Caps.
* For finer control, use link_pads() and
* link_pads_filtered() to specify the pads to link on
* each element by name.
*
* Each element has a state (see Gst::State). You can get and set the state
* of an element with get_state() and set_state().
* Setting a state triggers a Gst::StateChange. To get a string representation
* of a Gst::State, use Gst::Enums::get_name().
*
* You can get and set a Gst::Clock on an element using get_clock()
* and set_clock().
* Some elements can provide a clock for the pipeline if
* the Gst::ELEMENT_FLAG_PROVIDE_CLOCK flag is set. With the
* provide_clock() method one can retrieve the clock provided by
* such an element.
* Not all elements require a clock to operate correctly. If the
* Gst::ELEMENT_FLAG_REQUIRE_CLOCK flag is set, a clock should be set on the
* element with set_clock().
*
* Note that clock selection and distribution is normally handled by the
* toplevel Gst::Pipeline so the clock functions are only to be used in very
* specific situations.
*
* Last reviewed on 2016-05-18 (1.8.0).
*
* @ingroup GstBaseClasses
*/
class Element : public Gst::Object
{
#ifndef DOXYGEN_SHOULD_SKIP_THIS
public:
using CppObjectType = Element;
using CppClassType = Element_Class;
using BaseObjectType = GstElement;
using BaseClassType = GstElementClass;
// noncopyable
Element(const Element&) = delete;
Element& operator=(const Element&) = delete;
private: friend class Element_Class;
static CppClassType element_class_;
protected:
explicit Element(const Glib::ConstructParams& construct_params);
explicit Element(GstElement* castitem);
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
public:
Element(Element&& src) noexcept;
Element& operator=(Element&& src) noexcept;
~Element() noexcept override;
/** Get the GType for this class, for use with the underlying GObject type system.
*/
static GType get_type() G_GNUC_CONST;
#ifndef DOXYGEN_SHOULD_SKIP_THIS
static GType get_base_type() G_GNUC_CONST;
#endif
///Provides access to the underlying C GObject.
GstElement* gobj() { return reinterpret_cast<GstElement*>(gobject_); }
///Provides access to the underlying C GObject.
const GstElement* gobj() const { return reinterpret_cast<GstElement*>(gobject_); }
///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
GstElement* gobj_copy();
private:
public:
/** Links this source element to the @a dest element.
* The link must be from source to destination - the other direction will not
* be tried. The function looks for existing pads that aren't linked yet. It
* will request new pads if necessary. Such pads need to be released manually
* when unlinking. If multiple links are possible, only one is established.
*
* Make sure you have added your elements to a bin or pipeline with
* Gst::Bin::add() before trying to link them.
*
* @param dest the Gst::Element containing the destination pad.
* @return the destination element for further linking if desired.
* @throws std::runtime_error If the elements could not be linked.
*/
Glib::RefPtr<Gst::Element> link(const Glib::RefPtr<Gst::Element>& dest);
/** Adds a pad (link point) to @a element. @a pad's parent will be set to @a element;
* see Gst::Object::set_parent() for refcounting information.
*
* Pads are not automatically activated so elements should perform the needed
* steps to activate the pad in case this pad is added in the PAUSED or PLAYING
* state. See Gst::Pad::set_active() for more information about activating pads.
*
* The pad and the element should be unlocked when calling this function.
*
* This function will emit the Gst::Element::signal_pad_added() signal on the element.
*
* @param pad The Gst::Pad to add to the element.
* @return <tt>true</tt> if the pad could be added. This function can fail when
* a pad with the same name already existed or the pad already had another
* parent.
*
* MT safe.
*/
bool add_pad(const Glib::RefPtr<Gst::Pad>& pad);
/** Creates a pad for each pad template that is always available.
* This function is only useful during object initialization of
* subclasses of Gst::Element.
*/
void create_all_pads();
/** Looks for an unlinked pad to which the given pad can link. It is not
* guaranteed that linking the pads will work, though it should work in most
* cases.
*
* This function will first attempt to find a compatible unlinked ALWAYS pad,
* and if none can be found, it will request a compatible REQUEST pad by looking
* at the templates of @a element.
*
* @param pad The Gst::Pad to find a compatible one for.
* @param caps The Gst::Caps to use as a filter.
* @return The Gst::Pad to which a link
* can be made, or <tt>nullptr</tt> if one cannot be found. Gst::Object::unref()
* after usage.
*/
Glib::RefPtr<Gst::Pad> create_compatible_pad(const Glib::RefPtr<const Gst::Pad>& pad, const Glib::RefPtr<const Gst::Caps>& caps);
/** Retrieves a pad template from @a element that is compatible with @a compattempl.
* Pads from compatible templates can be linked together.
*
* @param compattempl The Gst::PadTemplate to find a compatible
* template for.
* @return A compatible Gst::PadTemplate,
* or <tt>nullptr</tt> if none was found. No unreferencing is necessary.
*/
Glib::RefPtr<Gst::PadTemplate> get_compatible_pad_template(const Glib::RefPtr<const Gst::PadTemplate>& compattempl);
/** Retrieves a pad template from @a element that is compatible with @a compattempl.
* Pads from compatible templates can be linked together.
*
* @param compattempl The Gst::PadTemplate to find a compatible
* template for.
* @return A compatible Gst::PadTemplate,
* or <tt>nullptr</tt> if none was found. No unreferencing is necessary.
*/
Glib::RefPtr<const Gst::PadTemplate> get_compatible_pad_template(const Glib::RefPtr<const Gst::PadTemplate>& compattempl) const;
//TODO: The documentation says "The pad should be released with gst_element_release_request_pad().", which is odd. murrayc
/** Retrieves a pad from the element by name (e.g.\ "src_\\%d"). This version only
* retrieves request pads. The pad should be released with
* release_request_pad().
*
* This method is slower than manually getting the pad template and calling
* request_pad() if the pads should have a specific name (e.g.
* @a name is "src_1" instead of "src_\\%u").
*
* @param name The name of the request Gst::Pad to retrieve.
* @return Requested Gst::Pad if found,
* otherwise <tt>nullptr</tt>. Release after usage.
*/
Glib::RefPtr<Gst::Pad> get_request_pad(const Glib::ustring& name);
//TODO: The documentation says "The pad should be released with gst_element_release_request_pad().", which is odd. murrayc
/** Retrieves a request pad from the element according to the provided template.
* Pad templates can be looked up using
* Gst::ElementFactory::get_static_pad_templates().
*
* The pad should be released with release_request_pad().
*
* @param templ A Gst::PadTemplate of which we want a pad of.
* @param name The name of the request Gst::Pad
* to retrieve. Can be <tt>nullptr</tt>.
* @param caps The caps of the pad we want to
* request. Can be <tt>nullptr</tt>.
* @return Requested Gst::Pad if found,
* otherwise <tt>nullptr</tt>. Release after usage.
*/
Glib::RefPtr<Gst::Pad> request_pad(const Glib::RefPtr<Gst::PadTemplate>& templ, const Glib::ustring& name, const Glib::RefPtr<const Gst::Caps>& caps);
/// A request_pad() convenience overload.
Glib::RefPtr<Gst::Pad> request_pad(const Glib::RefPtr<Gst::PadTemplate>& templ, const Glib::ustring& name);
/// A request_pad() convenience overload.
Glib::RefPtr<Gst::Pad> request_pad(const Glib::RefPtr<Gst::PadTemplate>& templ, const Glib::RefPtr<const Gst::Caps>& caps);
/// A request_pad() convenience overload.
Glib::RefPtr<Gst::Pad> request_pad(const Glib::RefPtr<Gst::PadTemplate>& templ);
/** Retrieves a pad from @a element by name. This version only retrieves
* already-existing (i.e. 'static') pads.
*
* @param name The name of the static Gst::Pad to retrieve.
* @return The requested Gst::Pad if
* found, otherwise <tt>nullptr</tt>. unref after usage.
*
* MT safe.
*/
Glib::RefPtr<Gst::Pad> get_static_pad(const Glib::ustring& name);
/** Retrieves a pad from @a element by name. This version only retrieves
* already-existing (i.e. 'static') pads.
*
* @param name The name of the static Gst::Pad to retrieve.
* @return The requested Gst::Pad if
* found, otherwise <tt>nullptr</tt>. unref after usage.
*
* MT safe.
*/
Glib::RefPtr<const Gst::Pad> get_static_pad(const Glib::ustring& name) const;
/** Use this function to signal that the element does not expect any more pads
* to show up in the current pipeline. This function should be called whenever
* pads have been added by the element itself. Elements with Gst::PAD_SOMETIMES
* pad templates use this in combination with autopluggers to figure out that
* the element is done initializing its pads.
*
* This function emits the Gst::Element::signal_no_more_pads() signal.
*
* MT safe.
*/
void no_more_pads();
/** Makes the element free the previously requested pad as obtained with
* get_request_pad().
* MT safe.
* @param pad The Gst::Pad to release.
*/
void release_request_pad(const Glib::RefPtr<Gst::Pad>& pad);
/** Removes @a pad from @a element. @a pad will be destroyed if it has not been
* referenced elsewhere using Gst::Object::unparent().
*
* This function is used by plugin developers and should not be used
* by applications. Pads that were dynamically requested from elements
* with request_pad() should be released with the
* release_request_pad() function instead.
*
* Pads are not automatically deactivated so elements should perform the needed
* steps to deactivate the pad in case this pad is removed in the PAUSED or
* PLAYING state. See Gst::Pad::set_active() for more information about
* deactivating pads.
*
* The pad and the element should be unlocked when calling this function.
*
* This function will emit the Gst::Element::signal_pad_removed() signal on the element.
*
* @param pad The Gst::Pad to remove from the element.
* @return <tt>true</tt> if the pad could be removed. Can return <tt>false</tt> if the
* pad does not belong to the provided element.
*
* MT safe.
*/
bool remove_pad(const Glib::RefPtr<Gst::Pad>& pad);
/** Retrieves an iterator of @a element's pads. The iterator should
* be freed after usage. Also more specialized iterators exists such as
* iterate_src_pads() or iterate_sink_pads().
*
* The order of pads returned by the iterator will be the order in which
* the pads were added to the element.
*
* @return The Gst::Iterator of Gst::Pad.
*
* MT safe.
*/
Gst::Iterator<Gst::Pad> iterate_pads();
/** Retrieves an iterator of @a element's pads. The iterator should
* be freed after usage. Also more specialized iterators exists such as
* iterate_src_pads() or iterate_sink_pads().
*
* The order of pads returned by the iterator will be the order in which
* the pads were added to the element.
*
* @return The Gst::Iterator of Gst::Pad.
*
* MT safe.
*/
Gst::Iterator<const Gst::Pad> iterate_pads() const;
/** Retrieves an iterator of @a element's sink pads.
*
* The order of pads returned by the iterator will be the order in which
* the pads were added to the element.
*
* @return The Gst::Iterator of Gst::Pad.
*
* MT safe.
*/
Gst::Iterator<Gst::Pad> iterate_sink_pads();
/** Retrieves an iterator of @a element's sink pads.
*
* The order of pads returned by the iterator will be the order in which
* the pads were added to the element.
*
* @return The Gst::Iterator of Gst::Pad.
*
* MT safe.
*/
Gst::Iterator<const Gst::Pad> iterate_sink_pads() const;
/** Retrieves an iterator of @a element's source pads.
*
* The order of pads returned by the iterator will be the order in which
* the pads were added to the element.
*
* @return The Gst::Iterator of Gst::Pad.
*
* MT safe.
*/
Gst::Iterator<Gst::Pad> iterate_src_pads();
/** Retrieves an iterator of @a element's source pads.
*
* The order of pads returned by the iterator will be the order in which
* the pads were added to the element.
*
* @return The Gst::Iterator of Gst::Pad.
*
* MT safe.
*/
Gst::Iterator<const Gst::Pad> iterate_src_pads() const;
/** Unlinks all source pads of the source element with all sink pads
* of the sink element to which they are linked.
*
* If the link has been made using link(), it could have created an
* requestpad, which has to be released using release_request_pad().
*
* @param dest The sink Gst::Element to unlink.
*/
void unlink(const Glib::RefPtr<Gst::Element>& dest);
/** Sets the context of the element. Increases the refcount of the context.
*
* MT safe.
*
* @param context The Gst::Context to set.
*/
void set_context(const Glib::RefPtr<Gst::Context>& context);
//This is not like link() because link() was written to return the
//destination element as a convenience for further linking to compensate for
//C API's convenience function gst_element_link_many().
/** Links the two named pads of the source and destination elements.
* Side effect is that if one of the pads has no parent, it becomes a
* child of the parent of the other element. If they have different
* parents, the link fails.
*
* @param srcpadname The name of the Gst::Pad in source element
* or <tt>nullptr</tt> for any pad.
* @param dest The Gst::Element containing the destination pad.
* @param destpadname The name of the Gst::Pad in destination element,
* or <tt>nullptr</tt> for any pad.
* @return <tt>true</tt> if the pads could be linked, <tt>false</tt> otherwise.
*/
bool link_pads(const Glib::ustring& srcpadname, const Glib::RefPtr<Gst::Element>& dest, const Glib::ustring& destpadname);
/** Unlinks the two named pads of the source and destination elements.
*
* This is a convenience function for Gst::Pad::unlink().
*
* @param srcpadname The name of the Gst::Pad in source element.
* @param dest A Gst::Element containing the destination pad.
* @param destpadname The name of the Gst::Pad in destination element.
*/
void unlink_pads(const Glib::ustring& srcpadname, const Glib::RefPtr<Gst::Element>& dest, const Glib::ustring& destpadname);
//This is not like link() because link() was written to return the
//destination element as a convenience for further linking to compensate for
//C API's convenience function gst_element_link_many().
/** Links the two named pads of the source and destination elements. Side effect
* is that if one of the pads has no parent, it becomes a child of the parent of
* the other element. If they have different parents, the link fails. If @a caps
* is not <tt>nullptr</tt>, makes sure that the caps of the link is a subset of @a caps.
*
* @param srcpadname The name of the Gst::Pad in source element
* or <tt>nullptr</tt> for any pad.
* @param dest The Gst::Element containing the destination pad.
* @param destpadname The name of the Gst::Pad in destination element
* or <tt>nullptr</tt> for any pad.
* @param filter The Gst::Caps to filter the link,
* or <tt>nullptr</tt> for no filter.
* @return <tt>true</tt> if the pads could be linked, <tt>false</tt> otherwise.
*/
bool link_pads(const Glib::ustring& srcpadname, const Glib::RefPtr<Gst::Element>& dest, const Glib::ustring& destpadname, const Glib::RefPtr<Gst::Caps>& filter);
//This is not like link() because link() was written to return the
//destination element as a convenience for further linking to compensate for
//C API's convenience function gst_element_link_many().
/** Links the two named pads of the source and destination elements.
* Side effect is that if one of the pads has no parent, it becomes a
* child of the parent of the other element. If they have different
* parents, the link fails.
*
* Calling link_pads_full() with @a flags == Gst::PAD_LINK_CHECK_DEFAULT
* is the same as calling link_pads() and the recommended way of
* linking pads with safety checks applied.
*
* This is a convenience function for Gst::Pad::link_full().
*
* @param srcpadname The name of the Gst::Pad in source element
* or <tt>nullptr</tt> for any pad.
* @param dest The Gst::Element containing the destination pad.
* @param destpadname The name of the Gst::Pad in destination element,
* or <tt>nullptr</tt> for any pad.
* @param flags The Gst::PadLinkCheck to be performed when linking pads.
* @return <tt>true</tt> if the pads could be linked, <tt>false</tt> otherwise.
*/
bool link_pads(const Glib::ustring& srcpadname, const Glib::RefPtr<Gst::Element>& dest, const Glib::ustring& destpadname, PadLinkCheck flags);
/** Links @a src to @a dest using the given caps as filtercaps. The link must
* be from source to destination; the other direction will not be tried. The
* function looks for existing pads that aren't linked yet. It will request
* new pads if necessary. If multiple links are possible, only one is
* established.
*
* Make sure you have added your elements to a bin or pipeline with
* Gst::Bin::add() before trying to link them.
*
* @param dest The Gst::Element containing the destination pad.
* @param filter The Gst::Caps to filter the link.
* @return the destination element for further linking if desired.
* @throws std::runtime_error If the elements could not be linked.
*/
Glib::RefPtr<Gst::Element> link(const Glib::RefPtr<Gst::Element>& dest, const Glib::RefPtr<Gst::Caps>& filter);
/** Set the base time of an element. See get_base_time().
*
* MT safe.
*
* @param time The base time to set.
*/
void set_base_time(ClockTime time);
/** Returns the base time of the element. The base time is the
* absolute time of the clock when this element was last put to
* PLAYING. Subtracting the base time from the clock time gives
* the running time of the element.
*
* @return The base time of the element.
*
* MT safe.
*/
ClockTime get_base_time() const;
/** Set the start time of an element. The start time of the element is the
* running time of the element when it last went to the PAUSED state. In READY
* or after a flushing seek, it is set to 0.
*
* Toplevel elements like Gst::Pipeline will manage the start_time and
* base_time on its children. Setting the start_time to Gst::CLOCK_TIME_NONE
* on such a toplevel element will disable the distribution of the base_time to
* the children and can be useful if the application manages the base_time
* itself, for example if you want to synchronize capture from multiple
* pipelines, and you can also ensure that the pipelines have the same clock.
*
* MT safe.
*
* @param time The base time to set.
*/
void set_start_time(Gst::ClockTime time);
/** Returns the start time of the element. The start time is the
* running time of the clock when this element was last put to PAUSED.
*
* Usually the start_time is managed by a toplevel element such as
* Gst::Pipeline.
*
* MT safe.
*
* @return The start time of the element.
*/
Gst::ClockTime get_start_time() const;
/** Sets the bus of the element. Increases the refcount on the bus.
* For internal use only, unless you're testing elements.
*
* MT safe.
*
* @param bus The Gst::Bus to set.
*/
void set_bus(const Glib::RefPtr<Gst::Bus>& bus);
/** Returns the bus of the element. Note that only a Gst::Pipeline will provide a
* bus for the application.
*
* @return The element's Gst::Bus. unref after usage.
*
* MT safe.
*/
Glib::RefPtr<Gst::Bus> get_bus();
/** Returns the bus of the element. Note that only a Gst::Pipeline will provide a
* bus for the application.
*
* @return The element's Gst::Bus. unref after usage.
*
* MT safe.
*/
Glib::RefPtr<const Gst::Bus> get_bus() const;
/** Retrieves the factory that was used to create this element.
*
* @return The Gst::ElementFactory used for creating this
* element. no refcounting is needed.
*/
Glib::RefPtr<Gst::ElementFactory> get_factory();
/** Retrieves the factory that was used to create this element.
*
* @return The Gst::ElementFactory used for creating this
* element. no refcounting is needed.
*/
Glib::RefPtr<const Gst::ElementFactory> get_factory() const;
// We don't wrap the gst_element_get_name(), gst_element_set_name(),
// gst_element_get_parent(), and gst_element_set_parent() macros because they
// just calls the base (GstObject) class's functions anyway.
/** Sets the clock for the element. This function increases the
* refcount on the clock. Any previously set clock on the object
* is unreffed.
*
* @param clock The Gst::Clock to set for the element.
* @return <tt>true</tt> if the element accepted the clock. An element can refuse a
* clock when it, for example, is not able to slave its internal clock to the
* @a clock or when it requires a specific clock to operate.
*
* MT safe.
*/
bool set_clock(const Glib::RefPtr<Gst::Clock>& clock);
/** Gets the currently configured clock of the element. This is the clock as was
* last set with set_clock().
*
* Elements in a pipeline will only have their clock set when the
* pipeline is in the PLAYING state.
*
* @return The Gst::Clock of the element. unref after usage.
*
* MT safe.
*/
Glib::RefPtr<Gst::Clock> get_clock();
/** Gets the currently configured clock of the element. This is the clock as was
* last set with set_clock().
*
* Elements in a pipeline will only have their clock set when the
* pipeline is in the PLAYING state.
*
* @return The Gst::Clock of the element. unref after usage.
*
* MT safe.
*/
Glib::RefPtr<const Gst::Clock> get_clock() const;
/** Get the clock provided by the given element.
* <note>An element is only required to provide a clock in the PAUSED
* state. Some elements can provide a clock in other states.</note>
*
* @return The GstClock provided by the
* element or <tt>nullptr</tt> if no clock could be provided. Unref after usage.
*
* MT safe.
*/
Glib::RefPtr<Gst::Clock> provide_clock();
/** Get the clock provided by the given element.
* <note>An element is only required to provide a clock in the PAUSED
* state. Some elements can provide a clock in other states.</note>
*
* @return The GstClock provided by the
* element or <tt>nullptr</tt> if no clock could be provided. Unref after usage.
*
* MT safe.
*/
Glib::RefPtr<const Gst::Clock> provide_clock() const;
/** Sets the state of the element. This function will try to set the
* requested state by going through all the intermediary states and calling
* the class's state change function for each.
*
* This function can return Gst::STATE_CHANGE_ASYNC, in which case the
* element will perform the remainder of the state change asynchronously in
* another thread.
* An application can use get_state() to wait for the completion
* of the state change or it can wait for a Gst::MESSAGE_ASYNC_DONE or
* Gst::MESSAGE_STATE_CHANGED on the bus.
*
* State changes to Gst::STATE_READY or Gst::STATE_NULL never return
* Gst::STATE_CHANGE_ASYNC.
*
* @param state The element's new Gst::State.
* @return Result of the state change using Gst::StateChangeReturn.
*
* MT safe.
*/
StateChangeReturn set_state(State state);
/** Gets the state of the element.
*
* For elements that performed an ASYNC state change, as reported by
* set_state(), this function will block up to the
* specified timeout value for the state change to complete.
* If the element completes the state change or goes into
* an error, this function returns immediately with a return value of
* Gst::STATE_CHANGE_SUCCESS or Gst::STATE_CHANGE_FAILURE respectively.
*
* For elements that did not return Gst::STATE_CHANGE_ASYNC, this function
* returns the current and pending state immediately.
*
* This function returns Gst::STATE_CHANGE_NO_PREROLL if the element
* successfully changed its state but is not able to provide data yet.
* This mostly happens for live sources that only produce data in
* Gst::STATE_PLAYING. While the state change return is equivalent to
* Gst::STATE_CHANGE_SUCCESS, it is returned to the application to signal that
* some sink elements might not be able to complete their state change because
* an element is not producing data to complete the preroll. When setting the
* element to playing, the preroll will complete and playback will start.
*
* @param state A pointer to Gst::State to hold the state.
* Can be <tt>nullptr</tt>.
* @param pending A pointer to Gst::State to hold the pending
* state. Can be <tt>nullptr</tt>.
* @param timeout A Gst::ClockTime to specify the timeout for an async
* state change or Gst::CLOCK_TIME_NONE for infinite timeout.
* @return Gst::STATE_CHANGE_SUCCESS if the element has no more pending state
* and the last state change succeeded, Gst::STATE_CHANGE_ASYNC if the
* element is still performing a state change or
* Gst::STATE_CHANGE_FAILURE if the last state change failed.
*
* MT safe.
*/
StateChangeReturn get_state(State& state, State& pending, ClockTime timeout) const;
/** Locks the state of an element, so state changes of the parent don't affect
* this element anymore.
*
* MT safe.
*
* @param locked_state <tt>true</tt> to lock the element's state.
* @return <tt>true</tt> if the state was changed, <tt>false</tt> if bad parameters were given
* or the elements state-locking needed no change.
*/
bool set_locked_state(gboolean locked_state);
/** Checks if the state of an element is locked.
* If the state of an element is locked, state changes of the parent don't
* affect the element.
* This way you can leave currently unused elements inside bins. Just lock their
* state before changing the state from Gst::STATE_NULL.
*
* MT safe.
*
* @return <tt>true</tt>, if the element's state is locked.
*/
bool is_locked_state() const;
/** Abort the state change of the element. This function is used
* by elements that do asynchronous state changes and find out
* something is wrong.
*
* This function should be called with the STATE_LOCK held.
*
* MT safe.
*/
void abort_state();
/** Commit the state change of the element and proceed to the next
* pending state if any. This function is used
* by elements that do asynchronous state changes.
* The core will normally call this method automatically when an
* element returned Gst::STATE_CHANGE_SUCCESS from the state change function.
*
* If after calling this method the element still has not reached
* the pending state, the next state change is performed.
*
* This method is used internally and should normally not be called by plugins
* or applications.
*
* @param ret The previous state return value.
* @return The result of the commit state change.
*
* MT safe.
*/
StateChangeReturn continue_state(StateChangeReturn ret);
/** Brings the element to the lost state. The current state of the
* element is copied to the pending state so that any call to
* get_state() will return Gst::STATE_CHANGE_ASYNC.
*
* An ASYNC_START message is posted. If the element was PLAYING, it will
* go to PAUSED. The element will be restored to its PLAYING state by
* the parent pipeline when it prerolls again.
*
* This is mostly used for elements that lost their preroll buffer
* in the Gst::STATE_PAUSED or Gst::STATE_PLAYING state after a flush,
* they will go to their pending state again when a new preroll buffer is
* queued. This function can only be called when the element is currently
* not in error or an async state change.
*
* This function is used internally and should normally not be called from
* plugins or applications.
*/
void lost_state();
/** Tries to change the state of the element to the same as its parent.
* If this function returns <tt>false</tt>, the state of element is undefined.
*
* @return <tt>true</tt>, if the element's state could be synced to the parent's state.
*
* MT safe.
*/
bool sync_state_with_parent();
/** Perform @a transition on @a element.
*
* This function must be called with STATE_LOCK held and is mainly used
* internally.
*
* @param transition The requested transition.
* @return The Gst::StateChangeReturn of the state transition.
*/
StateChangeReturn change_state(StateChange transition);
/** Post an error, warning or info message on the bus from inside an element.
*
* type must be of Gst::MESSAGE_ERROR, Gst::MESSAGE_WARNING or
* Gst::MESSAGE_INFO.
*
* MT safe.
*
* @param code The GError code belonging to the domain.
* @param line The source code line where the error was generated.
* @param type The GstMessageType.
* @param domain The GStreamer GError domain this message belongs to.
* @param text A text string to be used as a replacement for the default
* message connected to code.
* @param debug A debug message to be used as a replacement for the default
* debugging information.
* @param file The source code file where the error was generated.
* @param function The source code function where the error was generated.
*/
void post_message(int code, int line, MessageType type = Gst::MESSAGE_INFO,
const Glib::QueryQuark& domain = get_core_error_quark(),
const Glib::ustring& text = Glib::ustring(),
const Glib::ustring& debug = Glib::ustring(),
const Glib::ustring& file = Glib::ustring(),
const Glib::ustring& function = Glib::ustring());
/** Post a message on the element's Gst::Bus. This function takes ownership of the
* message; if you want to access the message after this call, you should add an
* additional reference before calling.
*
* @param message A Gst::Message to post.
* @return <tt>true</tt> if the message was successfully posted. The function returns
* <tt>false</tt> if the element did not have a bus.
*
* MT safe.
*/
bool post_message(Glib::RefPtr<Gst::Message>&& message);
/** Performs a query on the given element.
*
* For elements that don't implement a query handler, this function
* forwards the query to a random srcpad or to the peer of a
* random linked sinkpad of this element.
*
* Please note that some queries might need a running pipeline to work.
*
* @param query The Gst::Query.
* @return <tt>true</tt> if the query could be performed.
*
* MT safe.
*/
bool query(const Glib::RefPtr<Gst::Query>& query) const;
/** Queries an element to convert @a src_val in @a src_format to @a dest_format.
*
* @param src_format A Gst::Format to convert from.
* @param src_val A value to convert.
* @param dest_format The Gst::Format to convert to.
* @param dest_val A pointer to the result.
* @return <tt>true</tt> if the query could be performed.
*/
bool query_convert(Gst::Format src_format, gint64 src_val, Format dest_format, gint64& dest_val) const;
/** Queries an element (usually top-level pipeline or playbin element) for the
* stream position in nanoseconds. This will be a value between 0 and the
* stream duration (if the stream duration is known). This query will usually
* only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING
* state). The application will receive an ASYNC_DONE message on the pipeline
* bus when that is the case.
*
* If one repeatedly calls this function one can also create a query and reuse
* it in query().
*
* @param format The Gst::Format requested.
* @param cur A location in which to store the current
* position, or <tt>nullptr</tt>.
* @return <tt>true</tt> if the query could be performed.
*/
bool query_position(Gst::Format format, gint64& cur) const;
/// A query_position() convenience overload.
bool query_position(Gst::Format format) const;
/** Queries an element (usually top-level pipeline or playbin element) for the
* total stream duration in nanoseconds. This query will only work once the
* pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application
* will receive an ASYNC_DONE message on the pipeline bus when that is the case.
*
* If the duration changes for some reason, you will get a DURATION_CHANGED
* message on the pipeline bus, in which case you should re-query the duration
* using this function.
*
* @param format The Gst::Format requested.
* @param duration A location in which to store the total duration, or <tt>nullptr</tt>.
* @return <tt>true</tt> if the query could be performed.
*/
bool query_duration(Gst::Format format, gint64& duration) const;
/// A query_duration() convenience overload.
bool query_duration(Gst::Format format) const;
/** Simple API to perform a seek on the given element, meaning it just seeks
* to the given position relative to the start of the stream. For more complex
* operations like segment seeks (e.g. for looping) or changing the playback
* rate or seeking relative to the last configured playback segment you should
* use seek().
*
* In a completely prerolled PAUSED or PLAYING pipeline, seeking is always
* guaranteed to return <tt>true</tt> on a seekable media type or <tt>false</tt> when the media
* type is certainly not seekable (such as a live stream).
*
* Some elements allow for seeking in the READY state, in this
* case they will store the seek event and execute it when they are put to
* PAUSED. If the element supports seek in READY, it will always return <tt>true</tt> when
* it receives the event in the READY state.
*
* @param format A Gst::Format to execute the seek in, such as Gst::FORMAT_TIME.
* @param seek_flags Seek options; playback applications will usually want to use
* GST_SEEK_FLAG_FLUSH | GST_SEEK_FLAG_KEY_UNIT here.
* @param seek_pos Position to seek to (relative to the start); if you are doing
* a seek in Gst::FORMAT_TIME this value is in nanoseconds -
* multiply with Gst::SECOND to convert seconds to nanoseconds or
* with Gst::MSECOND to convert milliseconds to nanoseconds.
* @return <tt>true</tt> if the seek operation succeeded. Flushing seeks will trigger a
* preroll, which will emit Gst::MESSAGE_ASYNC_DONE.
*/
bool seek(Format format, SeekFlags seek_flags, gint64 seek_pos);
/** Sends a seek event to an element. See Gst::Event::new_seek() for the details of
* the parameters. The seek event is sent to the element using
* send_event().
*
* MT safe.
*
* @param rate The new playback rate.
* @param format The format of the seek values.
* @param flags The optional seek flags.
* @param cur_type The type and flags for the new start position.
* @param cur The value of the new start position.
* @param stop_type The type and flags for the new stop position.
* @param stop The value of the new stop position.
* @return <tt>true</tt> if the event was handled. Flushing seeks will trigger a
* preroll, which will emit Gst::MESSAGE_ASYNC_DONE.
*/
bool seek(double rate, Format format, SeekFlags flags, SeekType cur_type, gint64 cur, SeekType stop_type, gint64 stop);
/** Sends an event to an element. If the element doesn't implement an
* event handler, the event will be pushed on a random linked sink pad for
* downstream events or a random linked source pad for upstream events.
*
* This function takes ownership of the provided event so you should
* Gst::Event::ref() it if you want to reuse the event after this call.
*
* MT safe.
*
* @param event The Gst::Event to send to the element.
* @return <tt>true</tt> if the event was handled. Events that trigger a preroll (such
* as flushing seeks and steps) will emit Gst::MESSAGE_ASYNC_DONE.
*/
bool send_event(Glib::RefPtr<Gst::Event>&& event);
/// A send_event() convenience overload. Allows to re-use @a event parameter after function call.
bool send_event(const Glib::RefPtr<Gst::Event>& event);
/** Gets the context with @a context_type set on the element or <tt>nullptr</tt>.
*
* MT safe.
*
* @param context_type A name of a context to retrieve.
* @return A Gst::Context or <tt>nullptr</tt>.
*/
Glib::RefPtr<Gst::Context> get_context(const Glib::ustring& context_type);
/** Gets the context with @a context_type set on the element or <tt>nullptr</tt>.
*
* @param context_type A name of a context to retrieve.
* @return A Gst::Context or <tt>nullptr</tt>.
*/
Glib::RefPtr<Gst::Context> get_context_unlocked(const Glib::ustring& context_type);
/** Gets the contexts set on the element.
*
* MT safe.
*
* @return List of Gst::Context.
*/
std::vector< Glib::RefPtr<Gst::Context> > get_contexts();
/**
* @par Slot Prototype:
* <tt>void on_my_%no_more_pads()</tt>
*
* This signals that the element will not generate more dynamic pads.
* Note that this signal will usually be emitted from the context of
* the streaming thread.
*/
Glib::SignalProxy< void > signal_no_more_pads();
/**
* @par Slot Prototype:
* <tt>void on_my_%pad_added(const Glib::RefPtr<Gst::Pad>& new_pad)</tt>
*
* a new Gst::Pad has been added to the element. Note that this signal will
* usually be emitted from the context of the streaming thread. Also keep in
* mind that if you add new elements to the pipeline in the signal handler
* you will need to set them to the desired target state with
* Gst::Element::set_state() or Gst::Element::sync_state_with_parent().
*
* @param new_pad The pad that has been added.
*/
Glib::SignalProxy< void,const Glib::RefPtr<Gst::Pad>& > signal_pad_added();
/**
* @par Slot Prototype:
* <tt>void on_my_%pad_removed(const Glib::RefPtr<Gst::Pad>& old_pad)</tt>
*
* a Gst::Pad has been removed from the element
*
* @param old_pad The pad that has been removed.
*/
Glib::SignalProxy< void,const Glib::RefPtr<Gst::Pad>& > signal_pad_removed();
/** Called when a request pad is to be released.
*/
virtual void release_pad_vfunc(const Glib::RefPtr<Gst::Pad>& pad);
/** Called when a new pad is requested.
*/
virtual Glib::RefPtr<Gst::Pad> request_new_pad_vfunc(Glib::RefPtr<Gst::PadTemplate> templ, const Glib::ustring& name, const Glib::RefPtr<const Gst::Caps>& caps);
/** Get the state of the element.
*/
virtual StateChangeReturn get_state_vfunc(State& state, State& pending, ClockTime timeout) const;
/** Set a new state on the element.
*/
virtual StateChangeReturn set_state_vfunc(State state);
/** Called by set_state to perform an incremental state change.
*/
virtual StateChangeReturn change_state_vfunc(StateChange transition);
/** Called immediately after a new state was set.
*/
virtual void state_changed_vfunc(Gst::State oldstate, Gst::State newstate, Gst::State pending);
/** Set a Gst::Bus on the element.
*/
virtual void set_bus_vfunc(const Glib::RefPtr<Gst::Bus>& bus);
/** Gets the Gst::Clock provided by the element.
*/
virtual Glib::RefPtr<Gst::Clock> provide_clock_vfunc();
/** Set the Gst::Clock on the element.
*/
virtual bool set_clock_vfunc(const Glib::RefPtr<Gst::Clock>& clock);
/** Send a Gst::Event to the element.
*/
virtual bool send_event_vfunc(const Glib::RefPtr<Gst::Event>& event);
/** Perform a Gst::Query on the element.
*/
virtual bool query_vfunc(const Glib::RefPtr<Gst::Query>& query) const;
/** Set a Gst::Context on the element
*/
virtual void set_context_vfunc(const Glib::RefPtr<Gst::Context>& context);
/** Called when a message is posted on the element.
* Chain up to the parent class' handler to have it posted on the bus.
*/
virtual bool post_message_vfunc(const Glib::RefPtr<Gst::Message>& message);
Glib::RefPtr<Gst::PadTemplate> get_pad_template(const Glib::ustring &factory_name) const;
/**
* Sets specified property. Allows to create property-chain
* (e.g. element->property("location", "test.ogg")->property("num_buffers", 20);
*
* @param name The property name.
* @param value The property value.
*
* @return A this element.
*/
template<typename T>
Glib::RefPtr<Gst::Element> property(const Glib::ustring& name, const T& value)
{
set_property(name, value);
return Glib::RefPtr<Gst::Element>( dynamic_cast<Gst::Element*> (Glib::wrap_auto ((GObject*)(gobj()), true)) );
}
public:
public:
//C++ methods used to invoke GTK+ virtual functions:
protected:
//GTK+ Virtual Functions (override these to change behaviour):
//Default Signal Handlers::
/// This is a default handler for the signal signal_no_more_pads().
virtual void on_no_more_pads();
/// This is a default handler for the signal signal_pad_added().
virtual void on_pad_added(const Glib::RefPtr<Gst::Pad>& new_pad);
/// This is a default handler for the signal signal_pad_removed().
virtual void on_pad_removed(const Glib::RefPtr<Gst::Pad>& old_pad);
};
} // namespace Gst
namespace Glib
{
/** A Glib::wrap() method for this object.
*
* @param object The C instance.
* @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
* @result A C++ instance that wraps this C instance.
*
* @relates Gst::Element
*/
Glib::RefPtr<Gst::Element> wrap(GstElement* object, bool take_copy = false);
}
#endif /* _GSTREAMERMM_ELEMENT_H */
|