libam7xxx  0.1
Communication library for Actions Micro AM7XXX based USB projectors and DPFs
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Pages
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 1173 of file am7xxx.c.

1179 {
1180 
1181  am7xxx_device_info device_info;
1182  float width_ratio;
1183  float height_ratio;
1184  int ret;
1185 
1186  ret = am7xxx_get_device_info(dev, &device_info);
1187  if (ret < 0) {
1188  error(dev->ctx, "cannot get device info\n");
1189  return ret;
1190  }
1191 
1192  /*
1193  * Check if we need to rescale; if the input image fits the native
1194  * dimensions there is no need to, unless we want to upscale.
1195  */
1196  if (!upscale &&
1197  original_width <= device_info.native_width &&
1198  original_height <= device_info.native_height ) {
1199  debug(dev->ctx, "CASE 0, no rescaling, the original image fits already\n");
1200  *scaled_width = original_width;
1201  *scaled_height = original_height;
1202  return 0;
1203  }
1204 
1205  /* Input dimensions relative to the device native dimensions */
1206  width_ratio = (float)original_width / device_info.native_width;
1207  height_ratio = (float)original_height / device_info.native_height;
1208 
1209  if (width_ratio > height_ratio) {
1210  /*
1211  * The input is proportionally "wider" than the device viewport
1212  * so its height needs to be adjusted
1213  */
1214  debug(dev->ctx, "CASE 1, original image wider, adjust the scaled height\n");
1215  *scaled_width = device_info.native_width;
1216  *scaled_height = (unsigned int)lroundf(original_height / width_ratio);
1217  } else if (width_ratio < height_ratio) {
1218  /*
1219  * The input is proportionally "taller" than the device viewport
1220  * so its width needs to be adjusted
1221  */
1222  debug(dev->ctx, "CASE 2 original image taller, adjust the scaled width\n");
1223  *scaled_width = (unsigned int)lroundf(original_width / height_ratio);
1224  *scaled_height = device_info.native_height;
1225  } else {
1226  debug(dev->ctx, "CASE 3, just rescale, same aspect ratio already\n");
1227  *scaled_width = device_info.native_width;
1228  *scaled_height = device_info.native_height;
1229  }
1230  debug(dev->ctx, "scaled dimensions: %dx%d\n", *scaled_width, *scaled_height);
1231 
1232  return 0;
1233 }
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:1127
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 1112 of file am7xxx.c.

1113 {
1114  if (dev == NULL) {
1115  fatal("dev must not be NULL!\n");
1116  return -EINVAL;
1117  }
1118  if (dev->usb_device) {
1119  wait_for_trasfer_completed(dev);
1120  libusb_release_interface(dev->usb_device, dev->desc->interface_number);
1121  libusb_close(dev->usb_device);
1122  dev->usb_device = NULL;
1123  }
1124  return 0;
1125 }
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 1127 of file am7xxx.c.

1129 {
1130  int ret;
1131  struct am7xxx_header h;
1132 
1133  if (dev->device_info) {
1134  memcpy(device_info, dev->device_info, sizeof(*device_info));
1135  return 0;
1136  }
1137 
1138  ret = send_command(dev, AM7XXX_PACKET_TYPE_DEVINFO);
1139  if (ret < 0)
1140  return ret;
1141 
1142  memset(&h, 0, sizeof(h));
1143  ret = read_header(dev, &h);
1144  if (ret < 0)
1145  return ret;
1146 
1147  if (h.packet_type != AM7XXX_PACKET_TYPE_DEVINFO) {
1148  error(dev->ctx, "expected packet type: %d, got %d instead!\n",
1149  AM7XXX_PACKET_TYPE_DEVINFO, h.packet_type);
1150  errno = ENOTSUP;
1151  return -ENOTSUP;
1152  }
1153 
1154  dev->device_info = malloc(sizeof(*dev->device_info));
1155  if (dev->device_info == NULL) {
1156  error(dev->ctx, "cannot allocate a device info (%s)\n",
1157  strerror(errno));
1158  return -ENOMEM;
1159  }
1160  memset(dev->device_info, 0, sizeof(*dev->device_info));
1161 
1162  dev->device_info->native_width = h.header_data.devinfo.native_width;
1163  dev->device_info->native_height = h.header_data.devinfo.native_height;
1164 #if 0
1165  /* No reason to expose these in the public API until we know what they mean */
1166  dev->device_info->unknown0 = h.header_data.devinfo.unknown0;
1167  dev->device_info->unknown1 = h.header_data.devinfo.unknown1;
1168 #endif
1169 
1170  return 0;
1171 }
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 1007 of file am7xxx.c.

1008 {
1009  int ret;
1010 
1011  *ctx = malloc(sizeof(**ctx));
1012  if (*ctx == NULL) {
1013  fatal("cannot allocate the context (%s)\n", strerror(errno));
1014  ret = -ENOMEM;
1015  goto out;
1016  }
1017  memset(*ctx, 0, sizeof(**ctx));
1018 
1019  /* Set the highest log level during initialization */
1020  (*ctx)->log_level = AM7XXX_LOG_TRACE;
1021 
1022  ret = libusb_init(&((*ctx)->usb_context));
1023  if (ret < 0)
1024  goto out_free_context;
1025 
1026  libusb_set_debug((*ctx)->usb_context, LIBUSB_LOG_LEVEL_INFO);
1027 
1028  ret = scan_devices(*ctx, SCAN_OP_BUILD_DEVLIST , 0, NULL);
1029  if (ret < 0) {
1030  error(*ctx, "scan_devices() failed\n");
1031  am7xxx_shutdown(*ctx);
1032  goto out;
1033  }
1034 
1035  /* Set a quieter log level as default for normal operation */
1036  (*ctx)->log_level = AM7XXX_LOG_ERROR;
1037  return 0;
1038 
1039 out_free_context:
1040  free(*ctx);
1041  *ctx = NULL;
1042 out:
1043  return ret;
1044 }
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:1046
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 1074 of file am7xxx.c.

1076 {
1077  int ret;
1078 
1079  if (ctx == NULL) {
1080  fatal("context must not be NULL!\n");
1081  return -EINVAL;
1082  }
1083 
1084  ret = scan_devices(ctx, SCAN_OP_OPEN_DEVICE, device_index, dev);
1085  if (ret < 0) {
1086  errno = ENODEV;
1087  goto out;
1088  } else if (ret > 0) {
1089  warning(ctx, "device %d already open\n", device_index);
1090  errno = EBUSY;
1091  ret = -EBUSY;
1092  goto out;
1093  }
1094 
1095  /* Philips/Sagemcom PicoPix projectors require that the DEVINFO packet
1096  * is the first one to be sent to the device in order for it to
1097  * successfully return the correct device information.
1098  *
1099  * So, if there is not a cached version of it (from a previous open),
1100  * we ask for device info at open time,
1101  */
1102  if ((*dev)->device_info == NULL) {
1103  ret = am7xxx_get_device_info(*dev, NULL);
1104  if (ret < 0)
1105  error(ctx, "cannot get device info\n");
1106  }
1107 
1108 out:
1109  return ret;
1110 }
int am7xxx_get_device_info(am7xxx_device *dev, am7xxx_device_info *device_info)
Get info about an am7xxx device.
Definition: am7xxx.c:1127
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 1069 of file am7xxx.c.

1070 {
1071  ctx->log_level = log_level;
1072 }
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 1307 of file am7xxx.c.

1308 {
1309  if (dev->desc->ops.set_power_mode == NULL) {
1310  warning(dev->ctx,
1311  "setting power mode is unsupported on this device\n");
1312  return 0;
1313  }
1314 
1315  return dev->desc->ops.set_power_mode(dev, power);
1316 }
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 1318 of file am7xxx.c.

1319 {
1320  if (dev->desc->ops.set_zoom_mode == NULL) {
1321  warning(dev->ctx,
1322  "setting zoom mode is unsupported on this device\n");
1323  return 0;
1324  }
1325 
1326  return dev->desc->ops.set_zoom_mode(dev, zoom);
1327 }
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 1046 of file am7xxx.c.

1047 {
1048  am7xxx_device *current;
1049 
1050  if (ctx == NULL) {
1051  fatal("context must not be NULL!\n");
1052  return;
1053  }
1054 
1055  current = ctx->devices_list;
1056  while (current) {
1057  am7xxx_device *next = current->next;
1058  am7xxx_close_device(current);
1059  free(current->device_info);
1060  free(current);
1061  current = next;
1062  }
1063 
1064  libusb_exit(ctx->usb_context);
1065  free(ctx);
1066  ctx = NULL;
1067 }
int am7xxx_close_device(am7xxx_device *dev)
Close an am7xxx_device.
Definition: am7xxx.c:1112
struct _am7xxx_device am7xxx_device
An opaque data type representing an am7xxx device.
Definition: am7xxx.h:46