Webcam.idl

/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2011 Raritan Inc. All rights reserved.
 */
 
#include <UserEvent.idl>
 
/** Webcam Management */
module webcam {
 
    /** PixelFormat */
    enumeration PixelFormat {
        MJPEG,    ///< Motion JPEG
        JPEG,     ///< JPEG
        RGB,      ///< RGB encoded
        YUV       ///< YUV encoded
    };
 
    /** PowerLineFrequency */
    enumeration PowerLineFrequency {
        NOT_SUPPORTED,
        HZ50,
        HZ60,
        DISABLED
    };
 
    /** Format */
    structure Format {
        int width;                ///< image width
        int height;               ///< image height
        PixelFormat pixelFormat;  ///< pixel format
    };
 
    /**
     * Controls
     *
     * All int values are normed to a range of 1 to 1000
     * 0 means "auto" if available, -1 means not supported by the webcam
     */
    structure Controls {
        int brightness;           ///< brightness
        int contrast;             ///< contrast
        int saturation;           ///< saturation
        int gain;                 ///< gain
        int gamma;                ///< gamma
        PowerLineFrequency powerLineFrequency; ///< power line frequency (50Hz, 60Hz or disabled)
    };
 
    /** Location */
    structure Location {
        string name;              ///< location name
        string x;                 ///< x
        string y;                 ///< y
        string z;                 ///< z
    };
 
    /** Image meta data */
    structure ImageMetaData {
        Format format;      ///< image format information
        long timestamp;           ///< image timestamp
        Location location;        ///< source webcam location
    };
 
    /** Image */
    structure Image {
        ImageMetaData meta;       ///< image meta data
        string data;              ///< base64 encoded image data
    };
 
    /** Webcam settings */
    structure Settings {
        Format format;        ///< currently selected image format
        Controls controls;        ///< image settings like brightness, contrast, gain, ...
        string name;              ///< webcam name
        Location location;        ///< webcam location
        int refreshInterval;      ///< in ms, toggle "video" and "static image" mode
    };
 
    /** Webcam information */
    structure Information {
        string id;                ///< port and camera specific ID string
        string model;             ///< camera model
        vector<Format> supportedFormats; ///< supported image formats
    };
 
    /** The webcam interface */
    interface Webcam {
        /**
         * Error codes
         */
        constant int NO_ERROR                   = 0; ///< Operation successful, no error
        constant int ERR_INVALID_PARAM          = 1; ///< Invalid parameter for an operation
 
        /**
         * This event is emitted after the settings of a webcam were changed
         */
        valueobject SettingsChangedEvent extends event.UserEvent {
            Settings oldSettings;  ///< the old settings
            Settings newSettings;  ///< the new settings
        };
 
        /**
         * Retrieve information of a specific webcam.
         *
         * @return Information
         */
        Information getInformation();
 
        /**
         * Retrieve settings of a specific webcam.
         *
         * @return Settings
         */
        Settings getSettings();
 
        /**
         * Change settings of a specific webcam.
         *
         * @param settings  New webcam settings
         *
         * @return 0 if success
         * @return 1 if any parameter is invalid
         */
        int setSettings(in Settings settings);
 
        /**
         * Apply webcam control settings without storing them
         *
         * @param controls  Control settings
         *
         * @return 0 if success
         * @return 1 if any parameter is invalid
         */
        int setControls(in Controls controls);
 
        /**
         * Retrieve the default value of the controls.
         *
         * @return Controls
         */
        Controls getControlDefaults();
    };
}