Creating new packets

GPAC uses several types of packets:

- packets holding data allocated by the framework. 

Examples:
```
//create blank packet of 20 bytes
dst_pck = outpid.new_packet(20);

//create packet using the given string as a payload
dst_pck = outpid.new_packet("MyString");

//setup array buffer
ab = new ArrayBuffer();
//create packet containing a copy of the array buffer data
dst_pck = outpid.new_packet(ab);
```

- packets holding references to data allocated by a filter. These are usually tracked by the source filter using a callback function to detect packet destruction. An example of this feature is dispatching a video frame from a grabber, in order to avoid memory copy.

Examples:
```
//setup array buffer
ab = new ArrayBuffer();
//create packet containing a reference to the array buffer. The reference is released when the packet is destroyed
dst_pck = outpid.new_packet(ab, true);

//same as above, but also use a callback function to get notification when packet is consumed
dst_pck = outpid.new_packet(ab, true, () => {
						//do something upon destruction of packet
					});

```

- packets holding references to other packets, typically used to forward all or part of an input packet. An example of this feature is cropping an input video packet into one or more smaller frames without copying the packet data, by adjusting strides and data pointers.

Examples:
```
//get source packet
src_pck = in_pid.get_packet();

//create packet containing a reference to the array buffer. The reference is released when the packet is destroyed
dst_pck = outpid.new_packet(src_pck, true);

//same as above, but also use a callback function to get notification when packet is consumed
dst_pck = outpid.new_packet(src_pck, true, () => {
						//do something upon destruction of packet
					});

```

- packets cloning source packets - this special mode is used to perform in-place processing of packet whenever possible; if a source packet is only used by the calling filter and allows in-place processing, the input data is transferred to the output packet with no copy. 

Examples:
```
//get source packet
src_pck = in_pid.get_packet();

//create packet containing a clone of the input packet. If the input data cannot be cloned, a copy of the data is done, otherwise an error is thrown
dst_pck = outpid.new_packet(src_pck);

//create packet containing an explicit copy of the input packet. Even if the input data could have been cloned, a copy of the data is done if possible, otherwise an error is thrown
dst_pck = outpid.new_packet(src_pck, false, true);
```

- packets holding references to data accessors available in the filter, currently only use to access internal color planes of a filter or underlying OpenGL textures. 
This type of packets cannot be created from JS, but they can be used for other operations (packet forwarding, texture setup).
Their data can be accessed from JS by creating a clone packet (regular filter for in-place data editing) or a detached clone (sink filters) 

```
//prepare at global scope or other a cached packet to reduce memory allocations while cloning packets
filter.cached_pck = null;


//get source packet
src_pck = in_pid.get_packet();

let data = null;
if (src_pck.frame_ifce) {
	//we want to edit and send the result, clone the packet
	if (output_pid) {
		dst_pck = outpid.new_packet(src_pck);	
		data = dst_pck.data;
	}
	//we want to read only (either sink or we do not send the modified input as the output)
	//we must clone the packet
	else {
		filter.cached_pck = src_pck.clone(filter.cached_pck);
		data = filter.cached_pck;
	}
}
```



Once a packet is created, you can assign packet info as well as built-in and user properties as usual:
```
dst_pck.dts = 100;
dst_pck.cts = 101;
dst_pck.sap=GF_FILTER_SAP1;
dst_pck.duration = 1;
dst_pck.set_prop('SenderNTP', get_cur_ntp() );
dst_pck.set_prop('MyUserProp', 'My User Data', true);

```

If needed, you can copy packet information from a source packet. This will copy all built-in and user properties and all packet info 

```
dst_pck.copy_props(src_pck);
```

Note that this property copy is done by default when constructing an output packet from a source packet.


When you're ready, it's time to send your packet:

```
dst_pck.send();
```

Once send, the packet cannot be resent: it is in a detached state and has no longer any underlying native packet. As a general rule, you should consider a packet send as no longer accessible.