struct _am7xxx_context;
typedef struct _am7xxx_context am7xxx_context;
-/**
+/**
* @typedef am7xxx_device
*
* An opaque data type representing an am7xxx device.
* 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.
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;
/**
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.
*
* @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