15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef PPAPI_CPP_VAR_ARRAY_BUFFER_H_ 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PPAPI_CPP_VAR_ARRAY_BUFFER_H_ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/cpp/var.h" 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// @file 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// This file defines the API for interacting with a JavaScript ArrayBuffer. 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace pp { 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// <code>VarArrayBuffer</code> provides a way to interact with JavaScript 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// ArrayBuffers, which represent a contiguous sequence of bytes. Note that 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// these vars are not part of the embedding page's DOM, and can only be 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// shared with JavaScript using the <code>PostMessage</code> and 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// <code>HandleMessage</code> functions of <code>Instance</code>. 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class VarArrayBuffer : public Var { 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 22c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// The default constructor constructs a <code>VarArrayBuffer</code> which is 23c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// 0 byte long. 24c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) VarArrayBuffer(); 25c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 26c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// Construct a <code>VarArrayBuffer</code> given a var for which 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// is_array_buffer() is true. This will refer to the same 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>ArrayBuffer</code> as var, but allows you to access methods 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// specific to <code>VarArrayBuffer</code>. 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] var An <code>ArrayBuffer</code> var. 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) explicit VarArrayBuffer(const Var& var); 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 34c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// Construct a new <code>VarArrayBuffer</code> which is 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>size_in_bytes</code> bytes long and initialized to zero. 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] size_in_bytes The size of the constructed 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>ArrayBuffer</code> in bytes. 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) explicit VarArrayBuffer(uint32_t size_in_bytes); 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Copy constructor. 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) VarArrayBuffer(const VarArrayBuffer& buffer) : Var(buffer) {} 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual ~VarArrayBuffer() {} 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This function assigns one <code>VarArrayBuffer</code> to another 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>VarArrayBuffer</code>. 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] other The <code>VarArrayBuffer</code> to be assigned. 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return The resulting <code>VarArrayBuffer</code>. 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) VarArrayBuffer& operator=(const VarArrayBuffer& other); 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This function assigns one <code>VarArrayBuffer</code> to another 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>VarArrayBuffer</code>. A Var's assignment operator is overloaded 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// here so that we can check for assigning a non-ArrayBuffer var to a 57c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// <code>VarArrayBuffer</code>. 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] other The <code>VarArrayBuffer</code> to be assigned. 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return The resulting <code>VarArrayBuffer</code> (as a Var&). 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual Var& operator=(const Var& other); 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// bytes. 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return The length of the <code>VarArrayBuffer</code> in bytes. 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) uint32_t ByteLength() const; 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Map() maps the <code>ArrayBuffer</code> in to the module's address space 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// and returns a pointer to the beginning of the internal buffer for 722a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) /// this <code>ArrayBuffer</code>. ArrayBuffers are copied when transmitted, 732a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) /// so changes to the underlying memory are not automatically available to 742a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) /// the embedding page. 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Note that calling Map() can be a relatively expensive operation. Use care 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// when calling it in performance-critical code. For example, you should call 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// it only once when looping over an <code>ArrayBuffer</code>. 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <strong>Example:</strong> 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @code 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// char* data = static_cast<char*>(array_buffer_var.Map()); 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// uint32_t byte_length = array_buffer_var.ByteLength(); 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// for (uint32_t i = 0; i < byte_length; ++i) 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// data[i] = 'A'; 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @endcode 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return A pointer to the internal buffer for this 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>ArrayBuffer</code>. 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void* Map(); 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Unmap() unmaps this <code>ArrayBuffer</code> var from the module address 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// space. Use this if you want to save memory but might want to call Map() 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// to map the buffer again later. 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void Unmap(); 97c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 98c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) private: 99c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) void ConstructWithSize(uint32_t size_in_bytes); 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace pp 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // PPAPI_CPP_VAR_ARRAY_BUFFER_H_ 105