X-Git-Url: https://git.ao2.it/libam7xxx.git/blobdiff_plain/dbb6f1e7ec9a0fb7ca077062864767d3b60ef813..1caaf22426a7442b45872faf7f9f108d9c66baf0:/src/am7xxx.h

diff --git a/src/am7xxx.h b/src/am7xxx.h
index 4fe9b00..51f9324 100644
--- a/src/am7xxx.h
+++ b/src/am7xxx.h
@@ -37,7 +37,7 @@ extern "C" {
 struct _am7xxx_context;
 typedef struct _am7xxx_context am7xxx_context;
 
-/** 
+/**
  * @typedef am7xxx_device
  *
  * An opaque data type representing an am7xxx device.
@@ -88,7 +88,7 @@ typedef enum {
  * An am7xxx device can operate in several power modes. A certain power mode
  * may have effect on the display brightness or on the device power
  * consumption.
- *		
+ *
  * @note Most am7xxx devices come with a Y-shaped USB cable with a Master and
  * a Slave connector, higher power modes may require that both connectors are
  * plugged in to the host system for the device to work properly.
@@ -99,9 +99,9 @@ typedef enum {
 typedef enum {
 	AM7XXX_POWER_OFF    = 0, /**< Display is powered off, no image shown. */
 	AM7XXX_POWER_LOW    = 1, /**< Low power consumption but also low brightness. */
-	AM7XXX_POWER_MIDDLE = 2, /**< Middle level of brightness. */
+	AM7XXX_POWER_MIDDLE = 2, /**< Middle level of brightness. This and upper modes need both the Master and Slave USB connectors plugged. */
 	AM7XXX_POWER_HIGH   = 3, /**< More brightness, but more power consumption. */
-	AM7XXX_POWER_TURBO  = 4, /**< Max brightness and power consumprion. This may need both the Master and Slave USB connectors plugged. */
+	AM7XXX_POWER_TURBO  = 4, /**< Max brightness and power consumption. */
 } am7xxx_power_mode;
 
 /**
@@ -179,6 +179,28 @@ int am7xxx_get_device_info(am7xxx_device *dev,
 			   am7xxx_device_info *device_info);
 
 /**
+ * Calculate the dimensions of an image to be shown on an am7xxx device.
+ *
+ * Before sending images bigger than the device native dimensions the user
+ * needs to rescale them, this utility function does the calculation in a way
+ * that the original image aspect ratio is preserved.
+ *
+ * @param[in] dev A pointer to the structure representing the device to get info of
+ * @param[in] upscale Whether to calculate scaled dimensions for images smaller than the native dimensions
+ * @param[in] original_width The width of the original image
+ * @param[in] original_height The height of the original image
+ * @param[out] scaled_width The width the rescaled image should have
+ * @param[out] scaled_height The height the rescaled image should have
+ *
+ * @return 0 on success, a negative value on error
+ */
+int am7xxx_calc_scaled_image_dimensions(am7xxx_device *dev,
+					unsigned int upscale,
+					unsigned int original_width,
+					unsigned int original_height,
+					unsigned int *scaled_width,
+					unsigned int *scaled_height);
+/**
  * Send an image for display on a am7xxx device.
  *
  * This is the function that actually makes the device display something.
@@ -187,9 +209,9 @@ int am7xxx_get_device_info(am7xxx_device *dev,
  *
  * @param[in] dev A pointer to the structure representing the device to get info of
  * @param[in] format The format the image is in (see @link am7xxx_image_format @endlink enum)
- * @param[in] width  The width of the image
+ * @param[in] width The width of the image
  * @param[in] height The height of the image
- * @param[in] image  A buffer holding data in the format specified by the format parameter
+ * @param[in] image A buffer holding data in the format specified by the format parameter
  * @param[in] image_size The size in bytes of the image buffer
  *
  * @return 0 on success, a negative value on error