Instruction set reference
HIPE_OP_SET_SRC
Sends the data of an image, audio or video file to an img, audio or video element, or a block of raw pixels to a canvas. In Hipe an element's source is always the data itself, never an address.
- location: The element to give the data to.
- arg[0]: The raw bytes of the file (or of this chunk of it).
- arg[1]: The mime type of the data, e.g. "image/jpeg" or "video/mp4". Optional for an img, where "image/png" is assumed. Required for audio and video.
- arg[2]: Optional. "1" if more chunks of the same file will follow. See "Sending a file in chunks".
- arg[3]: Optional, for chunked audio and video. The size of the whole file in bytes. See "Audio and video".
Sending a file in chunks
A large file can be sent over several HIPE_OP_SET_SRC instructions to the same location, so that the client doesn't have to hold it all in memory or send it as one huge instruction. Set arg[2] to "1" on every chunk except the last.
- arg[1] and arg[3] are read from the first chunk only.
- If you don't know which chunk is the last when you send it, send "1" with every chunk, then finish with one more instruction that has an empty arg[0] and no arg[2].
- A chunked file may be up to 500 MB, and a client may have up to 8 chunked files in progress at once. Beyond either limit the file is discarded without an error. A client that goes far beyond them is disconnected.
- A canvas can't be sent to in chunks.
Images
A chunked image is drawn progressively as its chunks arrive. The exception is an element that is already showing a complete image: it keeps showing that until the new one has fully arrived, then swaps, so that the user doesn't see a half-loaded replacement.
Audio and video
Sent as a single instruction, a file plays as soon as playback is started. Playback, speed and volume are controlled with HIPE_OP_AUDIOVIDEO_STATE.
Sent in chunks, when playback can start depends on arg[3]:
| arg[3] on the first chunk | What happens |
|---|---|
| The size of the whole file in bytes | Playback can start once the start of the file has arrived (typically its first tenth), and the element's own controls show how much has arrived. If playback catches up with the data, it pauses by itself and resumes when more has arrived. |
| Empty | Nothing plays until the last chunk has arrived, although the duration may be reported earlier. Use this when the total size isn't known in advance. |
Once the whole file has arrived, a chunked file behaves exactly like one sent in a single instruction, including seeking and looping.
To play something else in the same element, send the new file to it: the old one stops and is replaced.
Canvas
Sending arg[1] = "image/x-raw-rgba" to a canvas writes pixels straight into it (the equivalent of putImageData() in HTML).
- The canvas must already have a "2d" context selected with HIPE_OP_USE_CANVAS.
- arg[0] is 4 bytes per pixel in the order red, green, blue, alpha (each 0 to 255), row by row from the top, with nothing between rows and no header.
- By default the pixels fill the whole canvas, so arg[0] must be exactly width × height × 4 bytes. To write to part of the canvas, first set the area with the setSrcRegion method of HIPE_OP_CANVAS_ACTION; arg[0] must then match that area's size.
- If there is no context, or the size doesn't match, the instruction is ignored.
Notes
To read an image's data or a canvas's contents back, use HIPE_OP_GET_SRC.