libam7xxx  0.1
Communication library for Actions Micro AM7XXX based USB projectors and DPFs
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. More...
 
void am7xxx_shutdown (am7xxx_context *ctx)
 Cleanup the library data structures and free the context. More...
 
void am7xxx_set_log_level (am7xxx_context *ctx, am7xxx_log_level log_level)
 Set verbosity level of log messages. More...
 
int am7xxx_open_device (am7xxx_context *ctx, am7xxx_device **dev, unsigned int device_index)
 Open an am7xxx_device according to a index. More...
 
int am7xxx_close_device (am7xxx_device *dev)
 Close an am7xxx_device. More...
 
int am7xxx_get_device_info (am7xxx_device *dev, am7xxx_device_info *device_info)
 Get info about an am7xxx device. More...
 
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. More...
 
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. More...
 
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. More...
 
int am7xxx_set_power_mode (am7xxx_device *dev, am7xxx_power_mode power)
 Set the power mode of an am7xxx device. More...
 
int am7xxx_set_zoom_mode (am7xxx_device *dev, am7xxx_zoom_mode zoom)
 Set the zoom mode of an am7xxx device. More...
 

Detailed Description

Public libam7xxx API.

Definition in file am7xxx.h.

Enumeration Type Documentation

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  {
JPEG format.
Definition: am7xxx.h:81
am7xxx_image_format
The image formats accepted by the device.
Definition: am7xxx.h:80
Raw YUV in the NV12 variant.
Definition: am7xxx.h:82

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

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,
102  AM7XXX_POWER_MIDDLE = 2,
103  AM7XXX_POWER_HIGH = 3,
104  AM7XXX_POWER_TURBO = 4,
Max brightness and power consumption.
Definition: am7xxx.h:104
Middle level of brightness.
Definition: am7xxx.h:102
am7xxx_power_mode
The device power modes.
Definition: am7xxx.h:99
More brightness, but more power consumption.
Definition: am7xxx.h:103
Low power consumption but also low brightness.
Definition: am7xxx.h:101
Display is powered off, no image shown.
Definition: am7xxx.h:100

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,
Zoom test screen, the firmware version is shown as well.
Definition: am7xxx.h:126
Zoom 1: H Scale (changes aspect ratio).
Definition: am7xxx.h:124
Zoom Tele: available on some PicoPix models.
Definition: am7xxx.h:127
Original Size, as retrieved via am7xxx_device_info.
Definition: am7xxx.h:123
Zoom 2: H/V Scale (changes aspect ratio).
Definition: am7xxx.h:125
am7xxx_zoom_mode
The display zoom modes.
Definition: am7xxx.h:122

Function Documentation

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
Examples:
examples/am7xxx-play.c.

Definition at line 1257 of file am7xxx.c.

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

Definition at line 1196 of file am7xxx.c.

1197 {
1198  if (dev == NULL) {
1199  fatal("dev must not be NULL!\n");
1200  return -EINVAL;
1201  }
1202  if (dev->usb_device) {
1203  wait_for_trasfer_completed(dev);
1204  libusb_release_interface(dev->usb_device, dev->desc->interface_number);
1205  libusb_close(dev->usb_device);
1206  dev->usb_device = NULL;
1207  }
1208  return 0;
1209 }
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
Examples:
examples/picoproj.c.

Definition at line 1211 of file am7xxx.c.

1213 {
1214  int ret;
1215  struct am7xxx_header h;
1216 
1217  if (dev->device_info) {
1218  memcpy(device_info, dev->device_info, sizeof(*device_info));
1219  return 0;
1220  }
1221 
1222  ret = send_command(dev, AM7XXX_PACKET_TYPE_DEVINFO);
1223  if (ret < 0)
1224  return ret;
1225 
1226  memset(&h, 0, sizeof(h));
1227  ret = read_header(dev, &h);
1228  if (ret < 0)
1229  return ret;
1230 
1231  if (h.packet_type != AM7XXX_PACKET_TYPE_DEVINFO) {
1232  error(dev->ctx, "expected packet type: %d, got %d instead!\n",
1233  AM7XXX_PACKET_TYPE_DEVINFO, h.packet_type);
1234  errno = ENOTSUP;
1235  return -ENOTSUP;
1236  }
1237 
1238  dev->device_info = malloc(sizeof(*dev->device_info));
1239  if (dev->device_info == NULL) {
1240  error(dev->ctx, "cannot allocate a device info (%s)\n",
1241  strerror(errno));
1242  return -ENOMEM;
1243  }
1244  memset(dev->device_info, 0, sizeof(*dev->device_info));
1245 
1246  dev->device_info->native_width = h.header_data.devinfo.native_width;
1247  dev->device_info->native_height = h.header_data.devinfo.native_height;
1248 #if 0
1249  /* No reason to expose these in the public API until we know what they mean */
1250  dev->device_info->unknown0 = h.header_data.devinfo.unknown0;
1251  dev->device_info->unknown1 = h.header_data.devinfo.unknown1;
1252 #endif
1253 
1254  return 0;
1255 }
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
Examples:
examples/am7xxx-play.c, and examples/picoproj.c.

Definition at line 1089 of file am7xxx.c.

1090 {
1091  int ret;
1092 
1093  *ctx = malloc(sizeof(**ctx));
1094  if (*ctx == NULL) {
1095  fatal("cannot allocate the context (%s)\n", strerror(errno));
1096  ret = -ENOMEM;
1097  goto out;
1098  }
1099  memset(*ctx, 0, sizeof(**ctx));
1100 
1101  /* Set the highest log level during initialization */
1102  (*ctx)->log_level = AM7XXX_LOG_TRACE;
1103 
1104  ret = libusb_init(&((*ctx)->usb_context));
1105  if (ret < 0) {
1106  error(*ctx, "libusb_init failed: %s\n", libusb_error_name(ret));
1107  goto out_free_context;
1108  }
1109 
1110  libusb_set_debug((*ctx)->usb_context, LIBUSB_LOG_LEVEL_INFO);
1111 
1112  ret = scan_devices(*ctx, SCAN_OP_BUILD_DEVLIST , 0, NULL);
1113  if (ret < 0) {
1114  error(*ctx, "scan_devices() failed\n");
1115  am7xxx_shutdown(*ctx);
1116  goto out;
1117  }
1118 
1119  /* Set a quieter log level as default for normal operation */
1120  (*ctx)->log_level = AM7XXX_LOG_ERROR;
1121  return 0;
1122 
1123 out_free_context:
1124  free(*ctx);
1125  *ctx = NULL;
1126 out:
1127  return ret;
1128 }
Error messages, typically they describe API functions failures.
Definition: am7xxx.h:70
Verbose informations about the communication with the hardware.
Definition: am7xxx.h:74
void am7xxx_shutdown(am7xxx_context *ctx)
Cleanup the library data structures and free the context.
Definition: am7xxx.c:1130
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
Examples:
examples/am7xxx-play.c, and examples/picoproj.c.

Definition at line 1158 of file am7xxx.c.

1160 {
1161  int ret;
1162 
1163  if (ctx == NULL) {
1164  fatal("context must not be NULL!\n");
1165  return -EINVAL;
1166  }
1167 
1168  ret = scan_devices(ctx, SCAN_OP_OPEN_DEVICE, device_index, dev);
1169  if (ret < 0) {
1170  errno = ENODEV;
1171  goto out;
1172  } else if (ret > 0) {
1173  warning(ctx, "device %d already open\n", device_index);
1174  errno = EBUSY;
1175  ret = -EBUSY;
1176  goto out;
1177  }
1178 
1179  /* Philips/Sagemcom PicoPix projectors require that the DEVINFO packet
1180  * is the first one to be sent to the device in order for it to
1181  * successfully return the correct device information.
1182  *
1183  * So, if there is not a cached version of it (from a previous open),
1184  * we ask for device info at open time,
1185  */
1186  if ((*dev)->device_info == NULL) {
1187  ret = am7xxx_get_device_info(*dev, NULL);
1188  if (ret < 0)
1189  error(ctx, "cannot get device info\n");
1190  }
1191 
1192 out:
1193  return ret;
1194 }
int am7xxx_get_device_info(am7xxx_device *dev, am7xxx_device_info *device_info)
Get info about an am7xxx device.
Definition: am7xxx.c:1211
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
Examples:
examples/picoproj.c.
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
Examples:
examples/am7xxx-play.c.
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)
Examples:
examples/am7xxx-play.c, and examples/picoproj.c.

Definition at line 1153 of file am7xxx.c.

1154 {
1155  ctx->log_level = log_level;
1156 }
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
Examples:
examples/am7xxx-play.c, and examples/picoproj.c.

Definition at line 1391 of file am7xxx.c.

1392 {
1393  if (dev->desc->ops.set_power_mode == NULL) {
1394  warning(dev->ctx,
1395  "setting power mode is unsupported on this device\n");
1396  return 0;
1397  }
1398 
1399  return dev->desc->ops.set_power_mode(dev, power);
1400 }
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
Examples:
examples/am7xxx-play.c, and examples/picoproj.c.

Definition at line 1402 of file am7xxx.c.

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

Cleanup the library data structures and free the context.

Parameters
[in,out]ctxThe context to free.
Examples:
examples/am7xxx-play.c, and examples/picoproj.c.

Definition at line 1130 of file am7xxx.c.

1131 {
1132  am7xxx_device *current;
1133 
1134  if (ctx == NULL) {
1135  fatal("context must not be NULL!\n");
1136  return;
1137  }
1138 
1139  current = ctx->devices_list;
1140  while (current) {
1141  am7xxx_device *next = current->next;
1142  am7xxx_close_device(current);
1143  free(current->device_info);
1144  free(current);
1145  current = next;
1146  }
1147 
1148  libusb_exit(ctx->usb_context);
1149  free(ctx);
1150  ctx = NULL;
1151 }
int am7xxx_close_device(am7xxx_device *dev)
Close an am7xxx_device.
Definition: am7xxx.c:1196
struct _am7xxx_device am7xxx_device
An opaque data type representing an am7xxx device.
Definition: am7xxx.h:46