mirror of https://github.com/svaarala/duktape.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
88 lines
3.9 KiB
88 lines
3.9 KiB
name: duk_push_buffer
|
|
|
|
proto: |
|
|
void duk_push_buffer_object(duk_context *ctx, duk_idx_t idx_buffer, duk_size_t byte_offset, duk_size_t byte_length, duk_uint_t flags);
|
|
|
|
stack: |
|
|
[ ... buffer! ... ] -> [ ... buffer! ... bufobj! ] (when creating an ArrayBuffer or a view)
|
|
[ ... ArrayBuffer! ... ] -> [ ... ArrayBuffer! ... bufobj! ] (when creating a view)
|
|
|
|
summary: |
|
|
<p>Push a new buffer object or a buffer view object. An underlying plain
|
|
buffer or an ArrayBuffer (accepted when creating a view) is provided at index
|
|
<code>idx_buffer</code>. The type of the buffer or view is given in
|
|
<code>flags</code> (e.g. <code>DUK_BUFOBJ_UINT16ARRAY</code>). The active
|
|
range or "slice" used from the underlying buffer is indicated by
|
|
<code>byte_offset</code> and <code>byte_length</code>.</p>
|
|
|
|
<p>The available buffer types are:</p>
|
|
<table>
|
|
<tr><th>Define</th><th>Buffer/view type</th></tr>
|
|
<tr><td>DUK_BUFOBJ_NODEJS_BUFFER</td><td>Buffer (Node.js), a Uint8Array inheriting from Buffer.prototype</td></tr>
|
|
<tr><td>DUK_BUFOBJ_ARRAYBUFFER</td><td>ArrayBuffer</td></tr>
|
|
<tr><td>DUK_BUFOBJ_DATAVIEW</td><td>DataView</td></tr>
|
|
<tr><td>DUK_BUFOBJ_INT8ARRAY</td><td>Int8Array</td></tr>
|
|
<tr><td>DUK_BUFOBJ_UINT8ARRAY</td><td>Uint8Array</td></tr>
|
|
<tr><td>DUK_BUFOBJ_UINT8CLAMPEDARRAY</td><td>Uint8ClampedArray</td></tr>
|
|
<tr><td>DUK_BUFOBJ_INT16ARRAY</td><td>Int16Array</td></tr>
|
|
<tr><td>DUK_BUFOBJ_UINT16ARRAY</td><td>Uint16Array</td></tr>
|
|
<tr><td>DUK_BUFOBJ_INT32ARRAY</td><td>Int32Array</td></tr>
|
|
<tr><td>DUK_BUFOBJ_UINT32ARRAY</td><td>Uint32Array</td></tr>
|
|
<tr><td>DUK_BUFOBJ_FLOAT32ARRAY</td><td>Float32Array</td></tr>
|
|
<tr><td>DUK_BUFOBJ_FLOAT64ARRAY</td><td>Float64Array</td></tr>
|
|
</table>
|
|
|
|
<p>When anything other than an <code>ArrayBuffer</code> is created and
|
|
the backing buffer given as an argument is a plain buffer, an
|
|
<code>ArrayBuffer</code> backing the view is automatically created.
|
|
It is accessible through the <code>buffer</code> property of the view
|
|
object. The ArrayBuffer's internal byteOffset will be zero so that
|
|
the ArrayBuffer's index byteOffset matches the view's index 0. The
|
|
ArrayBuffer's byteLength will be <code>byte_offset + byte_length</code>
|
|
so that the view range is valid for the ArrayBuffer.</p>
|
|
|
|
<p>When creating an ArrayBuffer, it's strongly recommended that the
|
|
<code>byte_offset</code> argument be zero. Otherwise the external
|
|
<code>.byteOffset</code> property of any views constructed over the
|
|
ArrayBuffer will be misleading: the value will be relative to the
|
|
plain buffer underlying the ArrayBuffer, rather than relative to the
|
|
ArrayBuffer. For a zero <code>byte_offset</code> there is no difference
|
|
between the two offsets.</p>
|
|
|
|
<p>The underlying plain buffer should normally cover the range indicated by
|
|
the <code>byte_offset</code> and <code>byte_length</code> arguments, but
|
|
memory safety is guaranteed even if that is not the case. For example, an
|
|
attempt to read values outside the underlying buffer will return zero. The
|
|
underlying buffer size is intentionally not checked when creating a buffer
|
|
object: even if the buffer fully covered the byte range during creation, it
|
|
might be resized later.</p>
|
|
|
|
example: |
|
|
/* Map byte range [100,150[ of plain buffer at idx_plain_buf into a
|
|
* Uint16Array object which will have the following properties:
|
|
*
|
|
* - length: 25 (length in Uint16 elements)
|
|
* - byteLength: 50 (length in bytes)
|
|
* - byteOffset: 100 (byte offset to start of slice)
|
|
* - BYTES_PER_ELEMENT: 2 (Uint16)
|
|
*
|
|
* The Uint16Array's .buffer property will be an ArrayBuffer with the
|
|
* following properties:
|
|
*
|
|
* - byteLength: 200
|
|
* - internal byteOffset: 0
|
|
*/
|
|
|
|
duk_push_buffer_object(ctx, idx_plain_buf, 100, 50, DUK_BUFOBJ_UINT16ARRAY);
|
|
|
|
tags:
|
|
- stack
|
|
- bufferobject
|
|
|
|
seealso:
|
|
- duk_push_buffer
|
|
- duk_push_fixed_buffer
|
|
- duk_push_dynamic_buffer
|
|
- duk_push_external_buffer
|
|
|
|
introduced: 1.3.0
|
|
|