Loading...
Searching...
No Matches
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

typedef struct _am7xxx_context am7xxx_context

An opaque data type representing a context.

Examples
  examples/am7xxx-play.c, and examples/picoproj.c.

Definition at line 38 of file am7xxx.h.

## am7xxx_device

typedef struct _am7xxx_device am7xxx_device

An opaque data type representing an am7xxx device.

Examples
  examples/am7xxx-play.c, and examples/picoproj.c.

Definition at line 46 of file am7xxx.h.

## Enumeration Type Documentation

## am7xxx_image_format

enum 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.

Examples
  examples/am7xxx-play.c.

Definition at line 80 of file am7xxx.h.

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

## am7xxx_log_level

enum 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.

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

## am7xxx_power_mode

enum 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.

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

## am7xxx_zoom_mode

enum 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.

{
AM7XXX_ZOOM_ORIGINAL = 0,
AM7XXX_ZOOM_H = 1,
AM7XXX_ZOOM_H_V = 2,
AM7XXX_ZOOM_TEST = 3,
AM7XXX_ZOOM_TELE = 4,
} am7xxx_zoom_mode;
am7xxx_zoom_mode
am7xxx_zoom_mode
The display zoom modes.
Definition am7xxx.h:122
AM7XXX_ZOOM_H
@ AM7XXX_ZOOM_H
Zoom 1: H Scale (changes aspect ratio).
Definition am7xxx.h:124
AM7XXX_ZOOM_ORIGINAL
@ AM7XXX_ZOOM_ORIGINAL
Original Size, as retrieved via am7xxx_device_info.
Definition am7xxx.h:123
AM7XXX_ZOOM_TELE
@ AM7XXX_ZOOM_TELE
Zoom Tele: available on some PicoPix models.
Definition am7xxx.h:127
AM7XXX_ZOOM_TEST
@ AM7XXX_ZOOM_TEST
Zoom test screen, the firmware version is shown as well.
Definition am7xxx.h:126
AM7XXX_ZOOM_H_V
@ 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] | dev | A pointer to the structure representing the device to get info of
  [in] | upscale | Whether to calculate scaled dimensions for images smaller than the native dimensions
  [in] | original_width | The width of the original image
  [in] | original_height | The height of the original image
  [out] | scaled_width | The width the rescaled image should have
  [out] | scaled_height | The height the rescaled image should have

Returns
  0 on success, a negative value on error

Definition at line 1269 of file am7xxx.c.

{
am7xxx_device_info device_info;
float width_ratio;
float height_ratio;
int ret;
ret = am7xxx_get_device_info(dev, &device_info);
if (ret < 0) {
error(dev->ctx, "cannot get device info\n");
return ret;
}
/*
* Check if we need to rescale; if the input image fits the native
* dimensions there is no need to, unless we want to upscale.
*/
if (!upscale &&
original_width <= device_info.native_width &&
original_height <= device_info.native_height ) {
debug(dev->ctx, "CASE 0, no rescaling, the original image fits already\n");
*scaled_width = original_width;
*scaled_height = original_height;
return 0;
}
/* Input dimensions relative to the device native dimensions */
width_ratio = (float)original_width / device_info.native_width;
height_ratio = (float)original_height / device_info.native_height;
if (width_ratio > height_ratio) {
/*
* The input is proportionally "wider" than the device viewport
* so its height needs to be adjusted
*/
debug(dev->ctx, "CASE 1, original image wider, adjust the scaled height\n");
*scaled_width = device_info.native_width;
*scaled_height = (unsigned int)lroundf(original_height / width_ratio);
} else if (width_ratio < height_ratio) {
/*
* The input is proportionally "taller" than the device viewport
* so its width needs to be adjusted
*/
debug(dev->ctx, "CASE 2 original image taller, adjust the scaled width\n");
*scaled_width = (unsigned int)lroundf(original_width / height_ratio);
*scaled_height = device_info.native_height;
} else {
debug(dev->ctx, "CASE 3, just rescale, same aspect ratio already\n");
*scaled_width = device_info.native_width;
*scaled_height = device_info.native_height;
}
debug(dev->ctx, "scaled dimensions: %dx%d\n", *scaled_width, *scaled_height);
return 0;
}
am7xxx_device_info
A struct describing device specific properties.
Definition am7xxx.h:56
am7xxx_device_info::native_height
unsigned int native_height
The device native height.
Definition am7xxx.h:58
am7xxx_device_info::native_width
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] | dev | A 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.

{
if (dev == NULL) {
fatal("dev must not be NULL!\n");
return -EINVAL;
}
if (dev->usb_device) {
wait_for_trasfer_completed(dev);
libusb_release_interface(dev->usb_device, dev->desc->interface_number);
libusb_close(dev->usb_device);
dev->usb_device = NULL;
}
return 0;
}

## 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] | dev | A pointer to the structure representing the device to get info of
  [out] | device_info | A 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.

{
int ret;
struct am7xxx_header h;
/* if there is a cached copy of the device info, just return that */
if (dev->device_info)
goto return_value;
ret = send_command(dev, AM7XXX_PACKET_TYPE_DEVINFO);
if (ret < 0)
return ret;
memset(&h, 0, sizeof(h));
ret = read_header(dev, &h);
if (ret < 0)
return ret;
if (h.packet_type != AM7XXX_PACKET_TYPE_DEVINFO) {
error(dev->ctx, "expected packet type: %d, got %d instead!\n",
AM7XXX_PACKET_TYPE_DEVINFO, h.packet_type);
errno = EINVAL;
return -EINVAL;
}
dev->device_info = malloc(sizeof(*dev->device_info));
if (dev->device_info == NULL) {
error(dev->ctx, "cannot allocate a device info (%s)\n",
strerror(errno));
return -ENOMEM;
}
memset(dev->device_info, 0, sizeof(*dev->device_info));
dev->device_info->native_width = h.header_data.devinfo.native_width;
dev->device_info->native_height = h.header_data.devinfo.native_height;
#if 0
/* No reason to expose these in the public API until we know what they mean */
dev->device_info->unknown0 = h.header_data.devinfo.unknown0;
dev->device_info->unknown1 = h.header_data.devinfo.unknown1;
#endif
return_value:
if (device_info)
memcpy(device_info, dev->device_info, sizeof(*device_info));
return 0;
}

## am7xxx_init()

int am7xxx_init | ( | am7xxx_context ** | ctx | ) |

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

Parameters

  [out] | ctx | A 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.

{
int ret;
*ctx = malloc(sizeof(**ctx));
if (*ctx == NULL) {
fatal("cannot allocate the context (%s)\n", strerror(errno));
return -ENOMEM;
}
memset(*ctx, 0, sizeof(**ctx));
/* Set the highest log level during initialization */
(*ctx)->log_level = AM7XXX_LOG_TRACE;
ret = libusb_init(&((*ctx)->usb_context));
if (ret < 0) {
error(*ctx, "libusb_init failed: %s\n", libusb_error_name(ret));
goto out_free_context;
}
libusb_set_debug((*ctx)->usb_context, LIBUSB_LOG_LEVEL_INFO);
ret = scan_devices(*ctx, SCAN_OP_BUILD_DEVLIST , 0, NULL);
if (ret < 0) {
error(*ctx, "scan_devices() failed\n");
am7xxx_shutdown(*ctx);
goto out;
}
/* Set a quieter log level as default for normal operation */
(*ctx)->log_level = AM7XXX_LOG_ERROR;
return 0;
out_free_context:
free(*ctx);
*ctx = NULL;
out:
return ret;
}

## 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] | ctx | The context to open the device in
  [out] | dev | A pointer to the structure representing the device to open
  [in] | device_index | The index of the device on the bus

Returns
  0 on success, a negative value on error

Definition at line 1168 of file am7xxx.c.

{
int ret;
if (ctx == NULL) {
fatal("context must not be NULL!\n");
return -EINVAL;
}
ret = scan_devices(ctx, SCAN_OP_OPEN_DEVICE, device_index, dev);
if (ret < 0) {
errno = ENODEV;
goto out;
} else if (ret > 0) {
warning(ctx, "device %d already open\n", device_index);
errno = EBUSY;
ret = -EBUSY;
goto out;
}
/* Philips/Sagemcom PicoPix projectors require that the DEVINFO packet
* is the first one to be sent to the device in order for it to
* successfully return the correct device information.
*
* NOTE: am7xxx_get_device_info() will fetch the actual device info
* from the device only the very first time it's called for a given
* device, otherwise, it'll return a cached version of the device info
* (from a previous call to am7xxx_open_device(), for instance).
*/
ret = am7xxx_get_device_info(*dev, NULL);
if (ret < 0)
error(ctx, "cannot get device info\n");
out:
return ret;
}

## 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] | dev | A pointer to the structure representing the device to get info of
  [in] | format | The format the image is in (see am7xxx_image_format enum)
  [in] | width | The width of the image
  [in] | height | The height of the image
  [in] | image | A buffer holding data in the format specified by the format parameter
  [in] | image_size | The 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] | dev | A pointer to the structure representing the device to get info of
  [in] | format | The format the image is in (see am7xxx_image_format enum)
  [in] | width | The width of the image
  [in] | height | The height of the image
  [in] | image | A buffer holding data in the format specified by the format parameter
  [in] | image_size | The 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] | ctx | The context to set the log level for
  [in] | log_level | The verbosity level to use in the context (see am7xxx_log_level)

Definition at line 1163 of file am7xxx.c.

{
ctx->log_level = log_level;
}

## 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] | dev | A pointer to the structure representing the device to set power mode to
  [in] | power | The 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.

{
if (dev->desc->ops.set_power_mode == NULL) {
warning(dev->ctx,
"setting power mode is unsupported on this device\n");
return 0;
}
return dev->desc->ops.set_power_mode(dev, power);
}

## 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] | dev | A pointer to the structure representing the device to set zoom mode to
  [in] | zoom | The 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.

{
if (dev->desc->ops.set_zoom_mode == NULL) {
warning(dev->ctx,
"setting zoom mode is unsupported on this device\n");
return 0;
}
return dev->desc->ops.set_zoom_mode(dev, zoom);
}

## am7xxx_shutdown()

void am7xxx_shutdown | ( | am7xxx_context * | ctx | ) |

Cleanup the library data structures and free the context.

Parameters

  [in,out] | ctx | The context to free.

Definition at line 1140 of file am7xxx.c.

{
am7xxx_device *current;
if (ctx == NULL) {
fatal("context must not be NULL!\n");
return;
}
current = ctx->devices_list;
while (current) {
am7xxx_device *next = current->next;
am7xxx_close_device(current);
free(current->device_info);
free(current);
current = next;
}
libusb_exit(ctx->usb_context);
free(ctx);
ctx = NULL;
}
am7xxx_device
struct _am7xxx_device am7xxx_device
An opaque data type representing an am7xxx device.
Definition am7xxx.h:46