diff options
| -rw-r--r-- | ppapi/api/ppb_var_array_buffer.idl | 96 | ||||
| -rw-r--r-- | ppapi/c/ppb_var_array_buffer.h | 98 |
2 files changed, 111 insertions, 83 deletions
diff --git a/ppapi/api/ppb_var_array_buffer.idl b/ppapi/api/ppb_var_array_buffer.idl index 87a545a..b2b5b48 100644 --- a/ppapi/api/ppb_var_array_buffer.idl +++ b/ppapi/api/ppb_var_array_buffer.idl @@ -4,7 +4,8 @@ */ /** - * This file defines the <code>PPB_VarArrayBuffer</code> struct. + * This file defines the <code>PPB_VarArrayBuffer</code> struct providing + * a way to interact with JavaScript ArrayBuffers. */ label Chrome { @@ -12,72 +13,85 @@ label Chrome { }; /** - * PPB_VarArrayBuffer API. This provides a way to interact with JavaScript - * ArrayBuffers, which represent a contiguous sequence of bytes. To manage the - * reference count for a VarArrayBuffer, please see PPB_Var. Note that - * these Vars are not part of the embedding page's DOM, and can only be shared - * with JavaScript via pp::Instance's PostMessage and HandleMessage functions. + * The <code>PPB_VarArrayBuffer</code> interface provides a way to interact + * with JavaScript ArrayBuffers, which represent a contiguous sequence of + * bytes. Use <code>PPB_Var</code> to manage the reference count for a + * <code>VarArrayBuffer</code>. Note that these Vars are not part of the + * embedding page's DOM, and can only be shared with JavaScript using the + * <code>PostMessage</code> and <code>HandleMessage</code> functions of + * <code>pp::Instance</code>. */ [macro="PPB_VAR_ARRAY_BUFFER_INTERFACE"] interface PPB_VarArrayBuffer { /** - * Create a zero-initialized VarArrayBuffer. + * Create() creates a zero-initialized <code>VarArrayBuffer</code>. * - * @param[in] size_in_bytes The size of the ArrayBuffer that will be created. + * @param[in] size_in_bytes The size of the <code>ArrayBuffer</code> to + * be created. * - * @return A PP_Var which represents a VarArrayBuffer of the requested size - * with a reference count of 1. + * @return A <code>PP_Var</code> representing a <code>VarArrayBuffer</code> + * of the requested size and with a reference count of 1. */ PP_Var Create([in] uint32_t size_in_bytes); /** - * Retrieves the length of the VarArrayBuffer in bytes. On success, - * byte_length is set to the length of the given ArrayBuffer var. On failure, - * byte_length is unchanged (this could happen, for instance, if the given - * PP_Var is not of type PP_VARTYPE_ARRAY_BUFFER). Note that ByteLength() will - * successfully retrieve the the size of an ArrayBuffer even if the - * ArrayBuffer is not currently mapped. + * ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in + * bytes. On success, <code>byte_length</code> is set to the length of the + * given <code>ArrayBuffer</code> var. On failure, <code>byte_length</code> + * is unchanged (this could happen, for instance, if the given + * <code>PP_Var</code> is not of type <code>PP_VARTYPE_ARRAY_BUFFER</code>). + * Note that ByteLength() will successfully retrieve the size of an + * <code>ArrayBuffer</code> even if the <code>ArrayBuffer</code> is not + * currently mapped. * - * @param[in] array The ArrayBuffer whose length should be returned. + * @param[in] array The <code>ArrayBuffer</code> whose length should be + * returned. * * @param[out] byte_length A variable which is set to the length of the given - * ArrayBuffer on success. + * <code>ArrayBuffer</code> on success. * - * @return PP_TRUE on success, PP_FALSE on failure. + * @return <code>PP_TRUE</code> on success, <code>PP_FALSE</code> on failure. */ PP_Bool ByteLength([in] PP_Var array, [out] uint32_t byte_length); /** - * Maps the ArrayBuffer in to the module's address space and returns a pointer - * to the beginning of the buffer for the given ArrayBuffer PP_Var. Note that - * calling Map() can be a relatively expensive operation. Use care when - * calling it in performance-critical code. For example, you should call it - * only once when looping over an ArrayBuffer: + * Map() maps the <code>ArrayBuffer</code> in to the module's address space + * and returns a pointer to the beginning of the buffer for the given + * <code>ArrayBuffer PP_Var</code>. Note that calling Map() can be a + * relatively expensive operation. Use care when calling it in + * performance-critical code. For example, you should call it only once when + * looping over an <code>ArrayBuffer</code>. * - * <code> - * char* data = (char*)(array_buffer_if.Map(array_buffer_var)); - * uint32_t byte_length = 0; - * PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length); - * if (!ok) - * return DoSomethingBecauseMyVarIsNotAnArrayBuffer(); - * for (uint32_t i = 0; i < byte_length; ++i) - * data[i] = 'A'; - * </code> + * <strong>Example:</strong> * - * @param[in] array The ArrayBuffer whose internal buffer should be returned. + * @code + * char* data = (char*)(array_buffer_if.Map(array_buffer_var)); + * uint32_t byte_length = 0; + * PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length); + * if (!ok) + * return DoSomethingBecauseMyVarIsNotAnArrayBuffer(); + * for (uint32_t i = 0; i < byte_length; ++i) + * data[i] = 'A'; + * @endcode * - * @return A pointer to the internal buffer for this ArrayBuffer. Returns NULL - * if the given PP_Var is not of type PP_VARTYPE_ARRAY_BUFFER. + * @param[in] array The <code>ArrayBuffer</code> whose internal buffer should + * be returned. + * + * @return A pointer to the internal buffer for this + * <code>ArrayBuffer</code>. Returns <code>NULL</code> + * if the given <code>PP_Var</code> is not of type + * <code>PP_VARTYPE_ARRAY_BUFFER</code>. */ mem_t Map([in] PP_Var array); /** - * Unmaps the given ArrayBuffer var from the module address space. Use this if - * you want to save memory but might want to Map the buffer again later. The - * PP_Var remains valid and should still be released using PPB_Var when you - * are done with the ArrayBuffer. + * Unmap() unmaps the given <code>ArrayBuffer</code> var from the module + * address space. Use this if you want to save memory but might want to call + * Map() to map the buffer again later. The <code>PP_Var</code> remains valid + * and should still be released using <code>PPB_Var</code> when you are done + * with the <code>ArrayBuffer</code>. * - * @param[in] array The ArrayBuffer which should be released. + * @param[in] array The <code>ArrayBuffer</code> to be released. */ void Unmap([in] PP_Var array); }; diff --git a/ppapi/c/ppb_var_array_buffer.h b/ppapi/c/ppb_var_array_buffer.h index c9c285f..06d6852 100644 --- a/ppapi/c/ppb_var_array_buffer.h +++ b/ppapi/c/ppb_var_array_buffer.h @@ -3,7 +3,7 @@ * found in the LICENSE file. */ -/* From ppb_var_array_buffer.idl modified Thu Jan 26 14:50:50 2012. */ +/* From ppb_var_array_buffer.idl modified Thu Feb 16 14:06:44 2012. */ #ifndef PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_ #define PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_ @@ -18,7 +18,8 @@ /** * @file - * This file defines the <code>PPB_VarArrayBuffer</code> struct. + * This file defines the <code>PPB_VarArrayBuffer</code> struct providing + * a way to interact with JavaScript ArrayBuffers. */ @@ -27,68 +28,81 @@ * @{ */ /** - * PPB_VarArrayBuffer API. This provides a way to interact with JavaScript - * ArrayBuffers, which represent a contiguous sequence of bytes. To manage the - * reference count for a VarArrayBuffer, please see PPB_Var. Note that - * these Vars are not part of the embedding page's DOM, and can only be shared - * with JavaScript via pp::Instance's PostMessage and HandleMessage functions. + * The <code>PPB_VarArrayBuffer</code> interface provides a way to interact + * with JavaScript ArrayBuffers, which represent a contiguous sequence of + * bytes. Use <code>PPB_Var</code> to manage the reference count for a + * <code>VarArrayBuffer</code>. Note that these Vars are not part of the + * embedding page's DOM, and can only be shared with JavaScript using the + * <code>PostMessage</code> and <code>HandleMessage</code> functions of + * <code>pp::Instance</code>. */ struct PPB_VarArrayBuffer_1_0 { /** - * Create a zero-initialized VarArrayBuffer. + * Create() creates a zero-initialized <code>VarArrayBuffer</code>. * - * @param[in] size_in_bytes The size of the ArrayBuffer that will be created. + * @param[in] size_in_bytes The size of the <code>ArrayBuffer</code> to + * be created. * - * @return A PP_Var which represents a VarArrayBuffer of the requested size - * with a reference count of 1. + * @return A <code>PP_Var</code> representing a <code>VarArrayBuffer</code> + * of the requested size and with a reference count of 1. */ struct PP_Var (*Create)(uint32_t size_in_bytes); /** - * Retrieves the length of the VarArrayBuffer in bytes. On success, - * byte_length is set to the length of the given ArrayBuffer var. On failure, - * byte_length is unchanged (this could happen, for instance, if the given - * PP_Var is not of type PP_VARTYPE_ARRAY_BUFFER). Note that ByteLength() will - * successfully retrieve the the size of an ArrayBuffer even if the - * ArrayBuffer is not currently mapped. + * ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in + * bytes. On success, <code>byte_length</code> is set to the length of the + * given <code>ArrayBuffer</code> var. On failure, <code>byte_length</code> + * is unchanged (this could happen, for instance, if the given + * <code>PP_Var</code> is not of type <code>PP_VARTYPE_ARRAY_BUFFER</code>). + * Note that ByteLength() will successfully retrieve the size of an + * <code>ArrayBuffer</code> even if the <code>ArrayBuffer</code> is not + * currently mapped. * - * @param[in] array The ArrayBuffer whose length should be returned. + * @param[in] array The <code>ArrayBuffer</code> whose length should be + * returned. * * @param[out] byte_length A variable which is set to the length of the given - * ArrayBuffer on success. + * <code>ArrayBuffer</code> on success. * - * @return PP_TRUE on success, PP_FALSE on failure. + * @return <code>PP_TRUE</code> on success, <code>PP_FALSE</code> on failure. */ PP_Bool (*ByteLength)(struct PP_Var array, uint32_t* byte_length); /** - * Maps the ArrayBuffer in to the module's address space and returns a pointer - * to the beginning of the buffer for the given ArrayBuffer PP_Var. Note that - * calling Map() can be a relatively expensive operation. Use care when - * calling it in performance-critical code. For example, you should call it - * only once when looping over an ArrayBuffer: + * Map() maps the <code>ArrayBuffer</code> in to the module's address space + * and returns a pointer to the beginning of the buffer for the given + * <code>ArrayBuffer PP_Var</code>. Note that calling Map() can be a + * relatively expensive operation. Use care when calling it in + * performance-critical code. For example, you should call it only once when + * looping over an <code>ArrayBuffer</code>. * - * <code> - * char* data = (char*)(array_buffer_if.Map(array_buffer_var)); - * uint32_t byte_length = 0; - * PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length); - * if (!ok) - * return DoSomethingBecauseMyVarIsNotAnArrayBuffer(); - * for (uint32_t i = 0; i < byte_length; ++i) - * data[i] = 'A'; - * </code> + * <strong>Example:</strong> * - * @param[in] array The ArrayBuffer whose internal buffer should be returned. + * @code + * char* data = (char*)(array_buffer_if.Map(array_buffer_var)); + * uint32_t byte_length = 0; + * PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length); + * if (!ok) + * return DoSomethingBecauseMyVarIsNotAnArrayBuffer(); + * for (uint32_t i = 0; i < byte_length; ++i) + * data[i] = 'A'; + * @endcode * - * @return A pointer to the internal buffer for this ArrayBuffer. Returns NULL - * if the given PP_Var is not of type PP_VARTYPE_ARRAY_BUFFER. + * @param[in] array The <code>ArrayBuffer</code> whose internal buffer should + * be returned. + * + * @return A pointer to the internal buffer for this + * <code>ArrayBuffer</code>. Returns <code>NULL</code> + * if the given <code>PP_Var</code> is not of type + * <code>PP_VARTYPE_ARRAY_BUFFER</code>. */ void* (*Map)(struct PP_Var array); /** - * Unmaps the given ArrayBuffer var from the module address space. Use this if - * you want to save memory but might want to Map the buffer again later. The - * PP_Var remains valid and should still be released using PPB_Var when you - * are done with the ArrayBuffer. + * Unmap() unmaps the given <code>ArrayBuffer</code> var from the module + * address space. Use this if you want to save memory but might want to call + * Map() to map the buffer again later. The <code>PP_Var</code> remains valid + * and should still be released using <code>PPB_Var</code> when you are done + * with the <code>ArrayBuffer</code>. * - * @param[in] array The ArrayBuffer which should be released. + * @param[in] array The <code>ArrayBuffer</code> to be released. */ void (*Unmap)(struct PP_Var array); }; |