libam7xxx 0.1
Communication library for Actions Micro AM7XXX based USB projectors and DPFs
Loading...
Searching...
No Matches
Data Structures | Typedefs | Enumerations | Functions
am7xxx.h File Reference

Public libam7xxx API. More...

Go to the source code of this file.

Data Structures

struct  am7xxx_device_info
 A struct describing device specific properties. More...
 

Typedefs

typedef struct _am7xxx_context am7xxx_context
 An opaque data type representing a context.
 
typedef struct _am7xxx_device am7xxx_device
 An opaque data type representing an am7xxx device.
 

Enumerations

enum  am7xxx_log_level {
  AM7XXX_LOG_FATAL = 0 , AM7XXX_LOG_ERROR = 1 , AM7XXX_LOG_WARNING = 2 , AM7XXX_LOG_INFO = 3 ,
  AM7XXX_LOG_DEBUG = 4 , AM7XXX_LOG_TRACE = 5
}
 The verbosity level of logging messages. More...
 
enum  am7xxx_image_format { AM7XXX_IMAGE_FORMAT_JPEG = 1 , AM7XXX_IMAGE_FORMAT_NV12 = 2 }
 The image formats accepted by the device. More...
 
enum  am7xxx_power_mode {
  AM7XXX_POWER_OFF = 0 , AM7XXX_POWER_LOW = 1 , AM7XXX_POWER_MIDDLE = 2 , AM7XXX_POWER_HIGH = 3 ,
  AM7XXX_POWER_TURBO = 4
}
 The device power modes. More...
 
enum  am7xxx_zoom_mode {
  AM7XXX_ZOOM_ORIGINAL = 0 , AM7XXX_ZOOM_H = 1 , AM7XXX_ZOOM_H_V = 2 , AM7XXX_ZOOM_TEST = 3 ,
  AM7XXX_ZOOM_TELE = 4
}
 The display zoom modes. More...
 

Functions

int am7xxx_init (am7xxx_context **ctx)
 Initialize the library context and data structures, and scan for devices.
 
void am7xxx_shutdown (am7xxx_context *ctx)
 Cleanup the library data structures and free the context.
 
void am7xxx_set_log_level (am7xxx_context *ctx, am7xxx_log_level log_level)
 Set verbosity level of log messages.
 
int am7xxx_open_device (am7xxx_context *ctx, am7xxx_device **dev, unsigned int device_index)
 Open an am7xxx_device according to a index.
 
int am7xxx_close_device (am7xxx_device *dev)
 Close an am7xxx_device.
 
int am7xxx_get_device_info (am7xxx_device *dev, am7xxx_device_info *device_info)
 Get info about an am7xxx device.
 
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)
 Calculate the dimensions of an image to be shown on an am7xxx device.
 
int am7xxx_send_image (am7xxx_device *dev, am7xxx_image_format format, unsigned int width, unsigned int height, unsigned char *image, unsigned int image_size)
 Send an image for display on an am7xxx device.
 
int am7xxx_send_image_async (am7xxx_device *dev, am7xxx_image_format format, unsigned int width, unsigned int height, unsigned char *image, unsigned int image_size)
 Queue transfer of an image for display on an am7xxx device and return immediately.
 
int am7xxx_set_power_mode (am7xxx_device *dev, am7xxx_power_mode power)
 Set the power mode of an am7xxx device.
 
int am7xxx_set_zoom_mode (am7xxx_device *dev, am7xxx_zoom_mode zoom)
 Set the zoom mode of an am7xxx device.
 

Detailed Description

Public libam7xxx API.

Definition in file am7xxx.h.

Typedef Documentation

◆ am7xxx_context

An opaque data type representing a context.

Definition at line 38 of file am7xxx.h.

◆ am7xxx_device

An opaque data type representing an am7xxx device.

Definition at line 46 of file am7xxx.h.

Enumeration Type Documentation

◆ am7xxx_image_format

The image formats accepted by the device.

Enumerator
AM7XXX_IMAGE_FORMAT_JPEG 

JPEG format.

AM7XXX_IMAGE_FORMAT_NV12 

Raw YUV in the NV12 variant.

Definition at line 80 of file am7xxx.h.

80 {
am7xxx_image_format
The image formats accepted by the device.
Definition am7xxx.h:80
@ AM7XXX_IMAGE_FORMAT_JPEG
JPEG format.
Definition am7xxx.h:81
@ AM7XXX_IMAGE_FORMAT_NV12
Raw YUV in the NV12 variant.
Definition am7xxx.h:82

◆ am7xxx_log_level

The verbosity level of logging messages.

This can be set with am7xxx_set_log_level() and the level will be used internally by libam7xxx to adjust the granularity of the information exposed to the user about the internal library operations.

Enumerator
AM7XXX_LOG_FATAL 

Fatal messages, the user application should stop if it gets one of this.

AM7XXX_LOG_ERROR 

Error messages, typically they describe API functions failures.

AM7XXX_LOG_WARNING 

Warnings about conditions worth mentioning to the user.

AM7XXX_LOG_INFO 

Informations about the device operations.

AM7XXX_LOG_DEBUG 

Informations about the library internals.

AM7XXX_LOG_TRACE 

Verbose informations about the communication with the hardware.

Definition at line 68 of file am7xxx.h.

68 {
72 AM7XXX_LOG_INFO = 3,
am7xxx_log_level
The verbosity level of logging messages.
Definition am7xxx.h:68
@ AM7XXX_LOG_ERROR
Error messages, typically they describe API functions failures.
Definition am7xxx.h:70
@ AM7XXX_LOG_INFO
Informations about the device operations.
Definition am7xxx.h:72
@ AM7XXX_LOG_DEBUG
Informations about the library internals.
Definition am7xxx.h:73
@ AM7XXX_LOG_WARNING
Warnings about conditions worth mentioning to the user.
Definition am7xxx.h:71
@ AM7XXX_LOG_FATAL
Fatal messages, the user application should stop if it gets one of this.
Definition am7xxx.h:69
@ AM7XXX_LOG_TRACE
Verbose informations about the communication with the hardware.
Definition am7xxx.h:74

◆ am7xxx_power_mode

The device power modes.

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.
At higher power modes some devices may use a fan to cool down the internal hardware components, and hence may be noisier in this case.
Enumerator
AM7XXX_POWER_OFF 

Display is powered off, no image shown.

AM7XXX_POWER_LOW 

Low power consumption but also low brightness.

AM7XXX_POWER_MIDDLE 

Middle level of brightness.

This and upper modes need both the Master and Slave USB connectors plugged.

AM7XXX_POWER_HIGH 

More brightness, but more power consumption.

AM7XXX_POWER_TURBO 

Max brightness and power consumption.

Definition at line 99 of file am7xxx.h.

99 {
100 AM7XXX_POWER_OFF = 0,
101 AM7XXX_POWER_LOW = 1,
am7xxx_power_mode
The device power modes.
Definition am7xxx.h:99
@ AM7XXX_POWER_HIGH
More brightness, but more power consumption.
Definition am7xxx.h:103
@ AM7XXX_POWER_OFF
Display is powered off, no image shown.
Definition am7xxx.h:100
@ AM7XXX_POWER_TURBO
Max brightness and power consumption.
Definition am7xxx.h:104
@ AM7XXX_POWER_LOW
Low power consumption but also low brightness.
Definition am7xxx.h:101
@ AM7XXX_POWER_MIDDLE
Middle level of brightness.
Definition am7xxx.h:102

◆ am7xxx_zoom_mode

The display zoom modes.

An am7xxx device can display images using several zoom modes.

Note
Changing the zoom mode can change the aspect ratio of the displayed image.
On the zoom test screen the version of the firmware running on the device is shown as well (e.g SPI_V21.0.0_2011.03.18).
The Tele mode is available only on some PicoPix models, when using it the image is distorted like if a different lens was used, but the global aspect ratio of the image does not change.
Enumerator
AM7XXX_ZOOM_ORIGINAL 

Original Size, as retrieved via am7xxx_device_info.

AM7XXX_ZOOM_H 

Zoom 1: H Scale (changes aspect ratio).

AM7XXX_ZOOM_H_V 

Zoom 2: H/V Scale (changes aspect ratio).

AM7XXX_ZOOM_TEST 

Zoom test screen, the firmware version is shown as well.

AM7XXX_ZOOM_TELE 

Zoom Tele: available on some PicoPix models.

Definition at line 122 of file am7xxx.h.

122 {
124 AM7XXX_ZOOM_H = 1,
125 AM7XXX_ZOOM_H_V = 2,
126 AM7XXX_ZOOM_TEST = 3,
127 AM7XXX_ZOOM_TELE = 4,
am7xxx_zoom_mode
The display zoom modes.
Definition am7xxx.h:122
@ AM7XXX_ZOOM_H
Zoom 1: H Scale (changes aspect ratio).
Definition am7xxx.h:124
@ AM7XXX_ZOOM_ORIGINAL
Original Size, as retrieved via am7xxx_device_info.
Definition am7xxx.h:123
@ AM7XXX_ZOOM_TELE
Zoom Tele: available on some PicoPix models.
Definition am7xxx.h:127
@ AM7XXX_ZOOM_TEST
Zoom test screen, the firmware version is shown as well.
Definition am7xxx.h:126
@ AM7XXX_ZOOM_H_V
Zoom 2: H/V Scale (changes aspect ratio).
Definition am7xxx.h:125

Function Documentation

◆ am7xxx_calc_scaled_image_dimensions()

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 
)

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.

Parameters
[in]devA pointer to the structure representing the device to get info of
[in]upscaleWhether to calculate scaled dimensions for images smaller than the native dimensions
[in]original_widthThe width of the original image
[in]original_heightThe height of the original image
[out]scaled_widthThe width the rescaled image should have
[out]scaled_heightThe height the rescaled image should have
Returns
0 on success, a negative value on error

Definition at line 1269 of file am7xxx.c.

1275{
1276 am7xxx_device_info device_info;
1277 float width_ratio;
1278 float height_ratio;
1279 int ret;
1280
1281 ret = am7xxx_get_device_info(dev, &device_info);
1282 if (ret < 0) {
1283 error(dev->ctx, "cannot get device info\n");
1284 return ret;
1285 }
1286
1287 /*
1288 * Check if we need to rescale; if the input image fits the native
1289 * dimensions there is no need to, unless we want to upscale.
1290 */
1291 if (!upscale &&
1292 original_width <= device_info.native_width &&
1293 original_height <= device_info.native_height ) {
1294 debug(dev->ctx, "CASE 0, no rescaling, the original image fits already\n");
1295 *scaled_width = original_width;
1296 *scaled_height = original_height;
1297 return 0;
1298 }
1299
1300 /* Input dimensions relative to the device native dimensions */
1301 width_ratio = (float)original_width / device_info.native_width;
1302 height_ratio = (float)original_height / device_info.native_height;
1303
1304 if (width_ratio > height_ratio) {
1305 /*
1306 * The input is proportionally "wider" than the device viewport
1307 * so its height needs to be adjusted
1308 */
1309 debug(dev->ctx, "CASE 1, original image wider, adjust the scaled height\n");
1310 *scaled_width = device_info.native_width;
1311 *scaled_height = (unsigned int)lroundf(original_height / width_ratio);
1312 } else if (width_ratio < height_ratio) {
1313 /*
1314 * The input is proportionally "taller" than the device viewport
1315 * so its width needs to be adjusted
1316 */
1317 debug(dev->ctx, "CASE 2 original image taller, adjust the scaled width\n");
1318 *scaled_width = (unsigned int)lroundf(original_width / height_ratio);
1319 *scaled_height = device_info.native_height;
1320 } else {
1321 debug(dev->ctx, "CASE 3, just rescale, same aspect ratio already\n");
1322 *scaled_width = device_info.native_width;
1323 *scaled_height = device_info.native_height;
1324 }
1325 debug(dev->ctx, "scaled dimensions: %dx%d\n", *scaled_width, *scaled_height);
1326
1327 return 0;
1328}
A struct describing device specific properties.
Definition am7xxx.h:56
unsigned int native_height
The device native height.
Definition am7xxx.h:58
unsigned int native_width
The device native width.
Definition am7xxx.h:57

◆ am7xxx_close_device()

int am7xxx_close_device ( am7xxx_device dev)

Close an am7xxx_device.

Close an am7xxx_device so that it becomes available for some other user/process to open it.

Parameters
[in]devA pointer to the structure representing the device to close
Returns
0 on success, a negative value on error

Definition at line 1206 of file am7xxx.c.

1207{
1208 if (dev == NULL) {
1209 fatal("dev must not be NULL!\n");
1210 return -EINVAL;
1211 }
1212 if (dev->usb_device) {
1213 wait_for_trasfer_completed(dev);
1214 libusb_release_interface(dev->usb_device, dev->desc->interface_number);
1215 libusb_close(dev->usb_device);
1216 dev->usb_device = NULL;
1217 }
1218 return 0;
1219}

◆ am7xxx_get_device_info()

int am7xxx_get_device_info ( am7xxx_device dev,
am7xxx_device_info device_info 
)

Get info about an am7xxx device.

Get information about a device, in the form of a am7xxx_device_info structure.

Parameters
[in]devA pointer to the structure representing the device to get info of
[out]device_infoA pointer to the structure where to store the device info (see am7xxx_device_info)
Returns
0 on success, a negative value on error

Definition at line 1221 of file am7xxx.c.

1223{
1224 int ret;
1225 struct am7xxx_header h;
1226
1227 /* if there is a cached copy of the device info, just return that */
1228 if (dev->device_info)
1229 goto return_value;
1230
1231 ret = send_command(dev, AM7XXX_PACKET_TYPE_DEVINFO);
1232 if (ret < 0)
1233 return ret;
1234
1235 memset(&h, 0, sizeof(h));
1236 ret = read_header(dev, &h);
1237 if (ret < 0)
1238 return ret;
1239
1240 if (h.packet_type != AM7XXX_PACKET_TYPE_DEVINFO) {
1241 error(dev->ctx, "expected packet type: %d, got %d instead!\n",
1242 AM7XXX_PACKET_TYPE_DEVINFO, h.packet_type);
1243 errno = EINVAL;
1244 return -EINVAL;
1245 }
1246
1247 dev->device_info = malloc(sizeof(*dev->device_info));
1248 if (dev->device_info == NULL) {
1249 error(dev->ctx, "cannot allocate a device info (%s)\n",
1250 strerror(errno));
1251 return -ENOMEM;
1252 }
1253 memset(dev->device_info, 0, sizeof(*dev->device_info));
1254
1255 dev->device_info->native_width = h.header_data.devinfo.native_width;
1256 dev->device_info->native_height = h.header_data.devinfo.native_height;
1257#if 0
1258 /* No reason to expose these in the public API until we know what they mean */
1259 dev->device_info->unknown0 = h.header_data.devinfo.unknown0;
1260 dev->device_info->unknown1 = h.header_data.devinfo.unknown1;
1261#endif
1262
1263return_value:
1264 if (device_info)
1265 memcpy(device_info, dev->device_info, sizeof(*device_info));
1266 return 0;
1267}

◆ am7xxx_init()

int am7xxx_init ( am7xxx_context **  ctx)

Initialize the library context and data structures, and scan for devices.

Parameters
[out]ctxA pointer to the context the library will be used in.
Returns
0 on success, a negative value on error

Definition at line 1100 of file am7xxx.c.

1101{
1102 int ret;
1103
1104 *ctx = malloc(sizeof(**ctx));
1105 if (*ctx == NULL) {
1106 fatal("cannot allocate the context (%s)\n", strerror(errno));
1107 return -ENOMEM;
1108 }
1109 memset(*ctx, 0, sizeof(**ctx));
1110
1111 /* Set the highest log level during initialization */
1112 (*ctx)->log_level = AM7XXX_LOG_TRACE;
1113
1114 ret = libusb_init(&((*ctx)->usb_context));
1115 if (ret < 0) {
1116 error(*ctx, "libusb_init failed: %s\n", libusb_error_name(ret));
1117 goto out_free_context;
1118 }
1119
1120 libusb_set_debug((*ctx)->usb_context, LIBUSB_LOG_LEVEL_INFO);
1121
1122 ret = scan_devices(*ctx, SCAN_OP_BUILD_DEVLIST , 0, NULL);
1123 if (ret < 0) {
1124 error(*ctx, "scan_devices() failed\n");
1125 am7xxx_shutdown(*ctx);
1126 goto out;
1127 }
1128
1129 /* Set a quieter log level as default for normal operation */
1130 (*ctx)->log_level = AM7XXX_LOG_ERROR;
1131 return 0;
1132
1133out_free_context:
1134 free(*ctx);
1135 *ctx = NULL;
1136out:
1137 return ret;
1138}

◆ am7xxx_open_device()

int am7xxx_open_device ( am7xxx_context ctx,
am7xxx_device **  dev,
unsigned int  device_index 
)

Open an am7xxx_device according to a index.

The semantics of the 'device_index' argument follows the order of the devices as found when scanning the bus at am7xxx_init() time.

Note
When the user tries to open a device already opened the function returns -EBUSY and the device is left open.
Parameters
[in]ctxThe context to open the device in
[out]devA pointer to the structure representing the device to open
[in]device_indexThe index of the device on the bus
Returns
0 on success, a negative value on error

Definition at line 1168 of file am7xxx.c.

1170{
1171 int ret;
1172
1173 if (ctx == NULL) {
1174 fatal("context must not be NULL!\n");
1175 return -EINVAL;
1176 }
1177
1178 ret = scan_devices(ctx, SCAN_OP_OPEN_DEVICE, device_index, dev);
1179 if (ret < 0) {
1180 errno = ENODEV;
1181 goto out;
1182 } else if (ret > 0) {
1183 warning(ctx, "device %d already open\n", device_index);
1184 errno = EBUSY;
1185 ret = -EBUSY;
1186 goto out;
1187 }
1188
1189 /* Philips/Sagemcom PicoPix projectors require that the DEVINFO packet
1190 * is the first one to be sent to the device in order for it to
1191 * successfully return the correct device information.
1192 *
1193 * NOTE: am7xxx_get_device_info() will fetch the actual device info
1194 * from the device only the very first time it's called for a given
1195 * device, otherwise, it'll return a cached version of the device info
1196 * (from a previous call to am7xxx_open_device(), for instance).
1197 */
1198 ret = am7xxx_get_device_info(*dev, NULL);
1199 if (ret < 0)
1200 error(ctx, "cannot get device info\n");
1201
1202out:
1203 return ret;
1204}

◆ am7xxx_send_image()

int am7xxx_send_image ( am7xxx_device dev,
am7xxx_image_format  format,
unsigned int  width,
unsigned int  height,
unsigned char *  image,
unsigned int  image_size 
)

Send an image for display on an am7xxx device.

This is the function that actually makes the device display something. Static pictures can be sent just once and the device will keep showing them until another image get sent or some command resets or turns off the display.

Parameters
[in]devA pointer to the structure representing the device to get info of
[in]formatThe format the image is in (see am7xxx_image_format enum)
[in]widthThe width of the image
[in]heightThe height of the image
[in]imageA buffer holding data in the format specified by the format parameter
[in]image_sizeThe size in bytes of the image buffer
Returns
0 on success, a negative value on error

◆ am7xxx_send_image_async()

int am7xxx_send_image_async ( am7xxx_device dev,
am7xxx_image_format  format,
unsigned int  width,
unsigned int  height,
unsigned char *  image,
unsigned int  image_size 
)

Queue transfer of an image for display on an am7xxx device and return immediately.

This is the function that actually makes the device display something. Static pictures can be sent just once and the device will keep showing them until another image get sent or some command resets or turns off the display.

Note
This _async() variant makes a copy of the image buffer, so the caller is free to reuse the buffer just after the function returns.
Parameters
[in]devA pointer to the structure representing the device to get info of
[in]formatThe format the image is in (see am7xxx_image_format enum)
[in]widthThe width of the image
[in]heightThe height of the image
[in]imageA buffer holding data in the format specified by the format parameter
[in]image_sizeThe size in bytes of the image buffer
Returns
0 on success, a negative value on error

◆ am7xxx_set_log_level()

void am7xxx_set_log_level ( am7xxx_context ctx,
am7xxx_log_level  log_level 
)

Set verbosity level of log messages.

Note
The level is per-context.
Messages of level AM7XXX_LOG_FATAL are always shown, regardless of the value of the log_level parameter.
Parameters
[in]ctxThe context to set the log level for
[in]log_levelThe verbosity level to use in the context (see am7xxx_log_level)

Definition at line 1163 of file am7xxx.c.

1164{
1165 ctx->log_level = log_level;
1166}

◆ am7xxx_set_power_mode()

int am7xxx_set_power_mode ( am7xxx_device dev,
am7xxx_power_mode  power 
)

Set the power mode of an am7xxx device.

Note
When setting the mode to AM7XXX_POWER_OFF the display can't be turned on again by using only am7xxx_set_power_mode(), am7xxx_set_zoom_mode() has to be called first, the current guess is that the latter performs some other resets beside setting the zoom mode.
Parameters
[in]devA pointer to the structure representing the device to set power mode to
[in]powerThe power mode to put the device in (see am7xxx_power_mode enum)
Returns
0 on success, a negative value on error

Definition at line 1402 of file am7xxx.c.

1403{
1404 if (dev->desc->ops.set_power_mode == NULL) {
1405 warning(dev->ctx,
1406 "setting power mode is unsupported on this device\n");
1407 return 0;
1408 }
1409
1410 return dev->desc->ops.set_power_mode(dev, power);
1411}

◆ am7xxx_set_zoom_mode()

int am7xxx_set_zoom_mode ( am7xxx_device dev,
am7xxx_zoom_mode  zoom 
)

Set the zoom mode of an am7xxx device.

Note
When setting the mode to AM7XXX_ZOOM_TEST, the calling program might want to skip displaying actual images.
It looks like that power mode and zoom mode are related somehow wrt. resetting the operational mode after AM7XXX_POWER_OFF, applications can restore the display properly using this combination:
  • Off: power mode 0, zoom mode 3
  • On: power mode != 0, zoom mode != 3
Parameters
[in]devA pointer to the structure representing the device to set zoom mode to
[in]zoomThe zoom mode to put the device in (see am7xxx_zoom_mode enum)
Returns
0 on success, a negative value on error

Definition at line 1413 of file am7xxx.c.

1414{
1415 if (dev->desc->ops.set_zoom_mode == NULL) {
1416 warning(dev->ctx,
1417 "setting zoom mode is unsupported on this device\n");
1418 return 0;
1419 }
1420
1421 return dev->desc->ops.set_zoom_mode(dev, zoom);
1422}

◆ am7xxx_shutdown()

void am7xxx_shutdown ( am7xxx_context ctx)

Cleanup the library data structures and free the context.

Parameters
[in,out]ctxThe context to free.

Definition at line 1140 of file am7xxx.c.

1141{
1142 am7xxx_device *current;
1143
1144 if (ctx == NULL) {
1145 fatal("context must not be NULL!\n");
1146 return;
1147 }
1148
1149 current = ctx->devices_list;
1150 while (current) {
1151 am7xxx_device *next = current->next;
1152 am7xxx_close_device(current);
1153 free(current->device_info);
1154 free(current);
1155 current = next;
1156 }
1157
1158 libusb_exit(ctx->usb_context);
1159 free(ctx);
1160 ctx = NULL;
1161}
struct _am7xxx_device am7xxx_device
An opaque data type representing an am7xxx device.
Definition am7xxx.h:46