scriptup 0.0.0

data/sketchup-sdk-win/headers/SketchUpAPI/model/image.h

@@ -0,0 +1,288 @@
+// Copyright 2013 Trimble Inc.  All Rights Reserved
+
+/**
+ * @file
+ * @brief Interfaces for SUImageRef.
+ */
+#ifndef SKETCHUP_MODEL_IMAGE_H_
+#define SKETCHUP_MODEL_IMAGE_H_
+
+#include <SketchUpAPI/color.h>
+#include <SketchUpAPI/unicodestring.h>
+#include <SketchUpAPI/transformation.h>
+#include <SketchUpAPI/model/defs.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+@struct SUImageRef
+@extends SUDrawingElementRef
+@brief References an image object.
+*/
+
+/**
+@brief Converts from an \ref SUImageRef to an \ref SUEntityRef.
+       This is essentially an upcast operation.
+@param[in] image The given image reference.
+@related SUImageRef
+@return
+- The converted \ref SUEntityRef if image is a valid image.
+- If not, the returned reference will be invalid.
+*/
+SU_EXPORT SUEntityRef SUImageToEntity(SUImageRef image);
+
+/**
+@brief Converts from an \ref SUEntityRef to an \ref SUImageRef.
+       This is essentially a downcast operation so the given entity must be
+       convertible to an \ref SUImageRef.
+@param[in] entity The given entity reference.
+@related SUImageRef
+@return
+- The converted \ref SUImageRef if the downcast operation succeeds. If not, the
+returned reference will be invalid
+*/
+SU_EXPORT SUImageRef SUImageFromEntity(SUEntityRef entity);
+
+/**
+@brief Converts from an \ref SUImageRef to an \ref SUDrawingElementRef.
+       This is essentially an upcast operation.
+@param[in] image The given image reference.
+@related SUImageRef
+@return
+- The converted \ref SUEntityRef if image is a valid image
+- If not, the returned reference will be invalid
+*/
+SU_EXPORT SUDrawingElementRef SUImageToDrawingElement(SUImageRef image);
+
+/**
+@brief Converts from an \ref SUDrawingElementRef to an \ref SUImageRef.
+       This is essentially a downcast operation so the given element must be
+       convertible to an \ref SUImageRef.
+@param[in] drawing_elem The given element reference.
+@related SUImageRef
+@return
+- The converted \ref SUImageRef if the downcast operation succeeds
+- If not, the returned reference will be invalid
+*/
+SU_EXPORT SUImageRef SUImageFromDrawingElement(SUDrawingElementRef drawing_elem);
+
+/**
+@brief Creates a new image object from an image file specified by a path.
+       The created image must be subsequently added to the Entities of a model,
+       component definition or a group. Use SUModelRemoveComponentDefinitions()
+       to remove the image from a model.
+@param[out] image     The image object created.
+@param[in]  file_path The file path of the source image file.
+                      Assumed to be UTF-8 encoded.
+@related SUImageRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if image is NULL
+- \ref SU_ERROR_OVERWRITE_VALID if image already references a valid object
+*/
+SU_RESULT SUImageCreateFromFile(SUImageRef* image, const char* file_path);
+
+/**
+@brief Creates a new SketchUp model image object from an image representation
+       object. The created image must be subsequently added to the Entities of
+       a model, component definition or a group. Use
+       SUModelRemoveComponentDefinitions() to remove the image from a model.
+@since SketchUp 2017, API 5.0
+@param[out] image     The image object created.
+@param[in]  image_rep The basic image object retrieved.
+@related SUImageRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if image is NULL
+- \ref SU_ERROR_OVERWRITE_VALID if image already references a valid object
+- \ref SU_ERROR_INVALID_INPUT if image_rep is not a valid object
+- \ref SU_ERROR_NO_DATA if the image_rep contains no data
+*/
+SU_RESULT SUImageCreateFromImageRep(SUImageRef* image, SUImageRepRef image_rep);
+
+/**
+@brief Retrieves a basic image from a SketchUp model image.  The given image
+       representation object must have been constructed using one of the
+       SUImageRepCreate* functions. It must be released using
+       SUImageRepRelease().
+afterwards.
+@since SketchUp 2017, API 5.0
+@param[in]  image        The texture object.
+@param[out] image_rep The basic image object retrieved.
+@related SUImageRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if image_rep is NULL
+- \ref SU_ERROR_INVALID_OUTPUT if image_rep does not point to a valid \ref
+       SUImageRepRef object
+- \ref SU_ERROR_NO_DATA if there was no image data
+*/
+SU_RESULT SUImageGetImageRep(SUImageRef image, SUImageRepRef* image_rep);
+
+/**
+@brief Retrieves the name of an image object.
+@param[in]  image The image object.
+@param[out] name  The name retrieved.
+@related SUImageRef
+@deprecated This function returns a property that should not exist.
+            Use SUImageGetDefinition() and SUComponentDefinitionGetName()
+            instead.
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if name is NULL
+- \ref SU_ERROR_INVALID_OUTPUT if name does not point to a valid \ref
+  SUStringRef object
+*/
+SU_DEPRECATED_FUNCTION("SketchUp API 9.1")
+SU_RESULT SUImageGetName(SUImageRef image, SUStringRef* name);
+
+/**
+@brief Sets the name of an image object.
+@param[in] image The image object.
+@param[in] name  The name to set. Assumed to be UTF-8 encoded.
+@related SUImageRef
+@deprecated This function sets a property that should not exist.
+            Use SUImageGetDefinition() and SUComponentDefinitionSetName()
+            instead.
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_INPUT if name is NULL
+*/
+SU_DEPRECATED_FUNCTION("SketchUp API 9.1")
+SU_RESULT SUImageSetName(SUImageRef image, const char* name);
+
+/**
+@brief Retrieves the 3-dimensional homogeneous transform of an image object.
+@param[in]  image     The image object.
+@param[out] transform The transform retrieved.
+@related SUImageRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
+*/
+SU_RESULT SUImageGetTransform(SUImageRef image, struct SUTransformation* transform);
+
+/**
+@brief Sets the 3-dimensional homogeneous transform of an image object.
+@param[in] image     The image object.
+@param[in] transform The affine transform to set.
+@related SUImageRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL
+*/
+SU_RESULT SUImageSetTransform(SUImageRef image, const struct SUTransformation* transform);
+
+/**
+@brief Retrieves the image file name of an image object.
+@param[in]  image     The image object.
+@param[out] file_name The image file name retrieved.
+@related SUImageRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if file_name is NULL
+- \ref SU_ERROR_INVALID_OUTPUT if file_name does not point to a valid \ref
+  SUStringRef object
+*/
+SU_RESULT SUImageGetFileName(SUImageRef image, SUStringRef* file_name);
+
+/**
+@brief Retrieves the world dimensions of an image object.
+@param[in]  image  The image object.
+@param[out] width  The width dimension retrieved.
+@param[out] height The height dimension retrieved.
+@related SUImageRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if width or height is NULL
+*/
+SU_RESULT SUImageGetDimensions(SUImageRef image, double* width, double* height);
+
+/**
+@brief Retrieves the component definition of an image object.
+@since SketchUp 2021.1, API 9.1
+@param[in]  image     The image object.
+@param[out] component The component definition retrieved.
+@related SUImageRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p image is not a valid object
+- \ref SU_ERROR_OVERWRITE_VALID if \p component already refers to a valid object.
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p component is NULL
+*/
+SU_RESULT SUImageGetDefinition(SUImageRef image, SUComponentDefinitionRef* component);
+
+/**
+@brief Retrieves the width and height dimensions of an image object in pixels.
+@deprecated Will be removed in the next version of the SketchUp API. The
+            functionality is replaced by SUImageGetImageRep followed by
+            SUImageRepGetPixelDimensions.
+@param[in]  image  The image object.
+@param[out] width  The width dimension retrieved.
+@param[out] height The height dimension retrieved.
+@related SUImageRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if width or height is NULL
+*/
+SU_DEPRECATED_FUNCTION("SketchUp API 5.0")
+SU_RESULT SUImageGetPixelDimensions(SUImageRef image, size_t* width, size_t* height);
+
+/**
+@brief  Returns the total size and bits-per-pixel value of an image. This
+        function is useful to determine the size of the buffer necessary to be
+        passed into \ref SUImageGetData(). The returned data can be used along
+        with the returned bits-per-pixel value and the image dimensions to
+        compute RGBA values at individual pixels of the image.
+@deprecated Will be removed in the next version of the SketchUp API. The
+            functionality is replaced by SUImageGetImageRep followed by
+            SUImageRepGetDataSize.
+@param[in]  image          The image object.
+@param[out] data_size      The total size of the image data in bytes.
+@param[out] bits_per_pixel The number of bits per pixel of the image data.
+@related SUImageRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is an invalid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if data_size or bits_per_pixel is NULL
+*/
+SU_DEPRECATED_FUNCTION("SketchUp API 5.0")
+SU_RESULT SUImageGetDataSize(SUImageRef image, size_t* data_size, size_t* bits_per_pixel);
+
+/**
+@brief  Returns the pixel data for an image. The given array must be large enough
+        to hold the image's data. This size can be obtained by calling
+        \ref SUImageGetDataSize().
+@deprecated Will be removed in the next version of the SketchUp API. The
+            functionality is replaced by SUImageGetImageRep followed by
+            SUImageRepGetData.
+@param[in]  image      The image object.
+@param[in]  data_size  The size of the byte array.
+@param[out] pixel_data The image data retrieved.
+@related SUImageRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is an invalid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if pixel_data is NULL
+- \ref SU_ERROR_INSUFFICIENT_SIZE if data_size is insufficient for the image
+  data
+*/
+SU_DEPRECATED_FUNCTION("SketchUp API 5.0")
+SU_RESULT SUImageGetData(SUImageRef image, size_t data_size, SUByte pixel_data[]);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif
+
+#endif  // SKETCHUP_MODEL_IMAGE_H_

data/sketchup-sdk-win/headers/SketchUpAPI/model/image_rep.h

@@ -0,0 +1,275 @@
+// Copyright 2016 Trimble Inc. All Rights Reserved.
+
+/**
+ * @file
+ * @brief Interfaces for SUImageRepRef.
+ */
+#ifndef SKETCHUP_MODEL_IMAGE_REP_H_
+#define SKETCHUP_MODEL_IMAGE_REP_H_
+
+#include <SketchUpAPI/color.h>
+#include <SketchUpAPI/model/defs.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+@struct SUColorOrder
+@brief A simple struct with four indices indicating the ordering of color data
+       within 32-bit bitmap images. 32-bit bitmap images have 4 channels per
+       pixel: red, green, blue, and alpha where the alpha channel indicates the
+       transparency of the pixel. SketchUpAPI expects the channels to be in
+       different orders on Windows vs. Mac OS. Bitmap data is exposed in BGRA
+       and RGBA byte orders on Windows and Mac OS, respectively. The color
+       order indices facilitate platform independent code when it is necessary
+       to manipulate image pixel data. The struct's data also applies to 24-bit
+       bitmap images except that such images don't have an alpha channel so the
+       \ref SUColorOrder.alpha_index varaible can be ignored.
+@since SketchUp 2017, API 5.2
+*/
+struct SUColorOrder {
+  short red_index;    ///< Indicates the position of the red byte within a single
+                      ///< pixel's data.
+  short green_index;  ///< Indicates the position of the green byte within a
+                      ///< single pixel's data.
+  short blue_index;   ///< Indicates the position of the blue byte within a
+                      ///< single pixel's data.
+  short alpha_index;  ///< Indicates the position of the alpha byte within a
+                      ///< single pixel's data.
+};
+
+/**
+@brief Retrieves a \ref SUColorOrder indicating the order of color bytes within
+       32-bit images' pixel data.
+@since SketchUp 2017, API 5.2
+@related SUColorOrder
+@return a \ref SUColorOrder indicating the pixel color ordering of 32bit images.
+*/
+SU_EXPORT struct SUColorOrder SUGetColorOrder();
+
+/**
+@struct SUImageRepRef
+@brief References an image representation object.
+@since SketchUp 2017, API 5.0
+*/
+
+/**
+@brief Creates a new image object with no image data. Image data can be set
+       using any of SUImageRepCopy, SUImageRepSetData, SUImageRepLoadFile.
+@since SketchUp 2017, API 5.0
+@param[out] image The image object created.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if image is NULL
+- \ref SU_ERROR_OVERWRITE_VALID if image already references a valid object
+*/
+SU_RESULT SUImageRepCreate(SUImageRepRef* image);
+
+/**
+@brief Releases an image object.
+@since SketchUp 2017, API 5.0
+@param[in] image The image object.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is an invalid object
+- \ref SU_ERROR_NULL_POINTER_INPUT if image is NULL
+*/
+SU_RESULT SUImageRepRelease(SUImageRepRef* image);
+
+/**
+@brief Copies data from the copy_image to image.
+@since SketchUp 2017, API 5.0
+@param[in,out] image      The image object to be altered.
+@param[in]     copy_image The original image to copy from.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image or copy_image are not a valid objects
+*/
+SU_RESULT SUImageRepCopy(SUImageRepRef image, SUImageRepRef copy_image);
+
+/**
+@brief Sets the image data for the given image. Makes a copy of the data rather
+       than taking ownership.
+@since SketchUp 2017, API 5.0
+@param[in,out] image          The image object used to load the data.
+@param[in]     width          The width of the image in pixels.
+@param[in]     height         The height of the image in pixels.
+@param[in]     bits_per_pixel The number of bits per pixel.
+@param[in]     row_padding    The size in Bytes of row padding in each row of
+                              pixel_data.
+@param[in]     pixel_data     The raw image data.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_INPUT if pixel_data is NULL
+- \ref SU_ERROR_OUT_OF_RANGE if width or height are 0
+- \ref SU_ERROR_OUT_OF_RANGE if bits per pixel is not 8, 24, or 32
+*/
+SU_RESULT SUImageRepSetData(
+    SUImageRepRef image, size_t width, size_t height, size_t bits_per_pixel, size_t row_padding,
+    const SUByte pixel_data[]);
+
+/**
+@brief Loads image data from the specified file into the provided image.
+@since SketchUp 2017, API 5.0
+@param[in,out] image     The image object used to load the file.
+@param[in]     file_path The file path of the source image file. Assumed to be
+                         UTF-8 encoded.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if file_path is NULL
+- \ref SU_ERROR_SERIALIZATION if the load operation fails
+*/
+SU_RESULT SUImageRepLoadFile(SUImageRepRef image, const char* file_path);
+
+/**
+@brief Saves an image object to an image file specified by a path.
+@since SketchUp 2017, API 5.0
+@param[in] image     The image object.
+@param[in] file_path The file path of the destination image file. Assumed to be
+                     UTF-8 encoded.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
+- \ref SU_ERROR_NO_DATA if image contains no data
+- \ref SU_ERROR_SERIALIZATION if the save operation fails
+*/
+SU_RESULT SUImageRepSaveToFile(SUImageRepRef image, const char* file_path);
+
+/**
+@brief Retrieves the width and height dimensions of an image object in pixels.
+@since SketchUp 2017, API 5.0
+@param[in]  image  The image object.
+@param[out] width  The width dimension retrieved.
+@param[out] height The height dimension retrieved.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if width or height is NULL
+*/
+SU_RESULT SUImageRepGetPixelDimensions(SUImageRepRef image, size_t* width, size_t* height);
+
+/**
+@brief Retrieves the size of the row padding of an image, in bytes.
+@since SketchUp 2017, API 5.0
+@param[in]  image           The image object.
+@param[out] row_padding The row padding retrieved.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if row_padding is NULL
+ */
+SU_RESULT SUImageRepGetRowPadding(SUImageRepRef image, size_t* row_padding);
+
+/**
+@brief Resizes the dimensions of an image object to the given width and height
+       in pixels.
+@since SketchUp 2017, API 5.0
+@param[in] image The image object.
+@param[in] width  The new width.
+@param[in] height The new height.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_OUT_OF_RANGE if width or height are 0
+*/
+SU_RESULT SUImageRepResize(SUImageRepRef image, size_t width, size_t height);
+
+/**
+@brief Converts an image object to be 32 bits per pixel.
+@since SketchUp 2017, API 5.0
+@param[in] image  The image object.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is not a valid object
+- \ref SU_ERROR_NO_DATA if image contains no data
+*/
+SU_RESULT SUImageRepConvertTo32BitsPerPixel(SUImageRepRef image);
+
+/**
+@brief  Returns the total size and bits-per-pixel value of an image. This
+        function is useful to determine the size of the buffer necessary to be
+        passed into \ref SUImageRepGetData(). The returned data can be used
+        along with the returned bits-per-pixel value and the image dimensions to
+        compute RGBA values at individual pixels of the image.
+@since SketchUp 2017, API 5.0
+@param[in]  image          The image object.
+@param[out] data_size      The total size of the image data in bytes.
+@param[out] bits_per_pixel The number of bits per pixel of the image data.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is an invalid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if data_size or bits_per_pixel is NULL
+*/
+SU_RESULT SUImageRepGetDataSize(SUImageRepRef image, size_t* data_size, size_t* bits_per_pixel);
+
+/**
+@brief Returns the pixel data for an image. The given array must be large
+       enough to hold the image's data. This size can be obtained by calling
+       \ref SUImageRepGetDataSize().
+@since SketchUp 2017, API 5.0
+@param[in]  image      The image object.
+@param[in]  data_size  The size of the byte array.
+@param[out] pixel_data The image data retrieved.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is an invalid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if pixel_data is NULL
+- \ref SU_ERROR_INSUFFICIENT_SIZE if data_size is insufficient for the image
+data
+*/
+SU_RESULT SUImageRepGetData(SUImageRepRef image, size_t data_size, SUByte pixel_data[]);
+
+/**
+@brief Returns the color data of an image in a \ref SUColor array.
+@since SketchUp 2018, API 6.0
+@param[in]  image      The image object.
+@param[out] color_data The SUColor data retrieved.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is an invalid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if color_data is NULL
+- \ref SU_ERROR_UNSUPPORTED if the bytes per pixel of the image is invalid
+*/
+SU_RESULT SUImageRepGetDataAsColors(SUImageRepRef image, SUColor color_data[]);
+
+/**
+@brief Returns the color data given by the UV texture coordinates.
+@since SketchUp 2018, API 6.0
+@param[in]  image    The image object.
+@param[in]  u        The U texture coordinate.
+@param[in]  v        The V texture coordinate.
+@param[in]  bilinear The flag to set bilinear texture filtering. This
+                     interpolates the colors instead of picking the nearest
+                     neighbor.
+@param[out] color    The returned color.
+@related SUImageRepRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if image is an invalid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if color is NULL
+*/
+SU_RESULT SUImageRepGetColorAtUV(
+    SUImageRepRef image, double u, double v, bool bilinear, SUColor* color);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif
+
+#endif  // SKETCHUP_MODEL_IMAGE_REP_H_